From 8f3d51e95c770a5e8f61a2f324e404fad412b4f1 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Fri, 2 Jun 2023 12:34:07 -0400 Subject: [PATCH] Feature improve documentation (#329) Data type improvements: - Relocated data types into their own file for easier maintenance. - Updated data types to ensure consistency between specification and implementation. - Identify locations of data type schemas in data type specifications. Documentation Improvements: - Discuss use of regular expression dialects used in XML and JSON schema. #235 - Improved documentation around the regex dialects used in the data types. - Added documentation around whitespace restrictions to make clear how the data type implementations restrict leading and trailing whitespace. - Cleaned up and simplified the terminology. - Refactored and made terminology more internally consistent. - Aligned tutorial with updated terminology. - Moved some content out of the overview page into use case page. - Fixed inconsistencies in the tutorial. - Added a complete computer build example. - Removed many OSCAL references. - Added discussion of collapse groups. - Wrapped most terminology in italics. - Improved introduction section and terminology consistency. - Added the following sections: - Conventions Used in this Document: Discusses use of capitalized requirement words. - Graph Theoretical Basis of Metaschema: Discusses how a Metaschema module represents a graph. - Object-Oriented Basis of Metaschema: Discusses how a Metaschema module describes OO classes. - Reorganized specification pages into smaller sections. - Added a syntax outline that better supports reference navigation into the specification. - Some TODO markers remain for work that needs to be completed in a future PR. Publishing an incomplete specification to encourage more review of current materials. Other Improvements: - Integrated new work towards a USWDS 3.x Hugo theme. - Adding NPM files. Added NodeJS setup to website build. - Configured dart-sass to be installed on Hugo build. Had to relocate the package.json, etc to project root to make Hugo postcss work. - Cleaned up some extra unneeded files and corrected some content that was left in error. --------- Co-authored-by: Wendell Piez Co-authored-by: A.J. Stein --- .github/CONTENTS.md | 2 +- .github/ISSUE_TEMPLATE/README.md | 2 +- .github/dependabot.yml | 1 - .../workflows/workflow-generate-website.yml | 26 +- .../workflow-validate-repo-markdown.yml | 3 +- .gitignore | 11 +- CODE_OF_CONDUCT.md | 2 +- build/go.mod | 2 +- build/package-lock.json => package-lock.json | 1168 +++++++++++++++++ build/package.json => package.json | 5 +- schema/json/metaschema-datatypes.json | 28 +- schema/xml/metaschema-datatypes.xsd | 105 +- schema/xml/metaschema.xsd | 24 +- test-suite/README.md | 2 +- .../metaschema-xspec/markdown-types/readme.md | 2 +- .../schema-gen/make-metaschema-xsd.xsl | 2 +- website/.browserslistrc | 5 + website/.htmltest.yml | 7 + website/assets/scss/full-width.scss | 18 - website/assets/scss/header.scss | 38 - website/assets/scss/uswds-custom.scss | 12 - website/config.yaml | 7 +- website/content/_index.md | 14 +- website/content/contribute/_index.md | 7 +- website/content/contribute/contact.md | 4 +- website/content/specification/_index.md | 52 +- .../specification/computer-example.xml | 171 +++ .../content/specification/concepts/_index.md | 51 - .../concepts/architecture-mermaid.md | 38 - .../specification/concepts/terminology.md | 103 -- .../specification/{syntax => }/datatypes.md | 488 ++++--- website/content/specification/def-inst.svg | 92 ++ website/content/specification/def-inst.vsdx | Bin 0 -> 32341 bytes website/content/specification/glossary.md | 111 ++ website/content/specification/im-model.svg | 136 ++ website/content/specification/im-model.vsdx | Bin 0 -> 27790 bytes .../specification/information-modeling.md | 161 +++ website/content/specification/mapping.md | 91 ++ .../content/specification/mapping/_index.md | 22 - .../metaschema-information-elements.png | 0 website/content/specification/overview.md | 60 + .../content/specification/syntax/_index.md | 625 +++++---- .../specification/syntax/constraints.md | 44 + .../specification/syntax/definitions.md | 580 ++++++++ .../syntax/inline-definitions.md | 169 +++ .../content/specification/syntax/instances.md | 464 +++++++ .../content/specification/syntax/module.md | 273 ++++ .../tutorials/1-getting-started/_index.md | 158 +-- website/content/tutorials/_index.md | 7 +- website/content/use/_index.md | 26 +- website/layouts/partials/foot.html | 7 - website/layouts/partials/head.html | 28 - website/static/css/element-map.css | 11 + website/static/img/oscal-gears-icon-140.png | 0 website/static/img/oscal-gears-icon-32.png | 0 website/static/img/oscal-page-icon-180.png | 0 website/themes/uswds | 2 +- .../scss/_hugo-uswds-custom-styles.scss | 28 + website/themes/uswds-nist/config.yaml | 25 + .../uswds-nist/layouts/partials/foot.html | 30 + .../uswds-nist/layouts/partials/head.html | 2 + .../layouts/partials/top-banner.html | 1 + 62 files changed, 4572 insertions(+), 981 deletions(-) rename build/package-lock.json => package-lock.json (55%) rename build/package.json => package.json (73%) create mode 100644 website/.browserslistrc create mode 100644 website/.htmltest.yml delete mode 100644 website/assets/scss/full-width.scss delete mode 100644 website/assets/scss/header.scss delete mode 100644 website/assets/scss/uswds-custom.scss create mode 100644 website/content/specification/computer-example.xml delete mode 100644 website/content/specification/concepts/_index.md delete mode 100644 website/content/specification/concepts/architecture-mermaid.md delete mode 100644 website/content/specification/concepts/terminology.md rename website/content/specification/{syntax => }/datatypes.md (59%) create mode 100644 website/content/specification/def-inst.svg create mode 100644 website/content/specification/def-inst.vsdx create mode 100644 website/content/specification/glossary.md create mode 100644 website/content/specification/im-model.svg create mode 100644 website/content/specification/im-model.vsdx create mode 100644 website/content/specification/information-modeling.md create mode 100644 website/content/specification/mapping.md delete mode 100644 website/content/specification/mapping/_index.md rename website/content/specification/{concepts => }/metaschema-information-elements.png (100%) create mode 100644 website/content/specification/overview.md create mode 100644 website/content/specification/syntax/constraints.md create mode 100644 website/content/specification/syntax/definitions.md create mode 100644 website/content/specification/syntax/inline-definitions.md create mode 100644 website/content/specification/syntax/instances.md create mode 100644 website/content/specification/syntax/module.md delete mode 100644 website/layouts/partials/foot.html delete mode 100644 website/layouts/partials/head.html create mode 100644 website/static/css/element-map.css delete mode 100644 website/static/img/oscal-gears-icon-140.png delete mode 100644 website/static/img/oscal-gears-icon-32.png delete mode 100644 website/static/img/oscal-page-icon-180.png create mode 100644 website/themes/uswds-nist/assets/scss/_hugo-uswds-custom-styles.scss create mode 100644 website/themes/uswds-nist/config.yaml create mode 100644 website/themes/uswds-nist/layouts/partials/foot.html create mode 100644 website/themes/uswds-nist/layouts/partials/head.html create mode 100644 website/themes/uswds-nist/layouts/partials/top-banner.html diff --git a/.github/CONTENTS.md b/.github/CONTENTS.md index 48a7d4754..ff0a694c0 100644 --- a/.github/CONTENTS.md +++ b/.github/CONTENTS.md @@ -1,4 +1,4 @@ -# OSCAL GitHub Supporting Files +# GitHub Files This directory contains supporting files for Metaschema GitHub repository use. The structure and contents of the directory are as follows: diff --git a/.github/ISSUE_TEMPLATE/README.md b/.github/ISSUE_TEMPLATE/README.md index 91ffa7c3e..f532dc856 100644 --- a/.github/ISSUE_TEMPLATE/README.md +++ b/.github/ISSUE_TEMPLATE/README.md @@ -1,4 +1,4 @@ -# OSCAL GitHub Issue Template Files +# GitHub Issue Template Files This directory contains templates for creating new project issues in GitHub. The structure and contents of the directory are as follows: diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 2f11a6af1..a7b365258 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -33,7 +33,6 @@ updates: target-branch: "develop" - package-ecosystem: "npm" - directory: "/build" schedule: interval: "daily" target-branch: "develop" diff --git a/.github/workflows/workflow-generate-website.yml b/.github/workflows/workflow-generate-website.yml index d0214a3cd..1efce6214 100644 --- a/.github/workflows/workflow-generate-website.yml +++ b/.github/workflows/workflow-generate-website.yml @@ -109,11 +109,31 @@ jobs: go-version-file: '${{ env.BUILD_PATH }}/go.mod' cache: true cache-dependency-path: '${{ env.BUILD_PATH }}/go.sum' + - name: Set up NodeJS + uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c + with: + node-version-file: 'build/.nvmrc' + cache: 'npm' + cache-dependency-path: 'package-lock.json' + - name: Setup Dependencies + run: | + # NodeJS + # If you are a developer and need to modify the workflow, be sure to review + # the package.json and package-lock.json to ensure the following deps are + # at least installed (they will be updated by dependabot): + # - ajv-cli + # - ajv-formats + # - markdown-link-check + # - yaml-convert + npm install --loglevel verbose + echo "$PWD/node_modules/.bin/" >> $GITHUB_PATH - name: Install Hugo if: steps.cache-hugo.outputs.cache-hit != 'true' run: | cd "${{ env.BUILD_PATH }}" go install -tags "extended" github.com/gohugoio/hugo + - name: Install Dart Sass Embedded + run: sudo snap install dart-sass-embedded - name: Run Hugo run: | hugo --config "config.yaml,development-config.yaml" -v --debug --minify @@ -169,7 +189,7 @@ jobs: enable_jekyll: false publish_dir: ./website/public publish_branch: nist-pages - commit_user_name: OSCAL GitHub Actions Bot - commit_user_email: oscal@nist.gov - commit_author: OSCAL GitHub Actions Bot + commit_user_name: GitHub Actions Bot + commit_user_email: metaschema@nist.gov + commit_author: GitHub Actions Bot commit_message: Deploying website [ci deploy skip] diff --git a/.github/workflows/workflow-validate-repo-markdown.yml b/.github/workflows/workflow-validate-repo-markdown.yml index c37f408fb..0c4555e26 100644 --- a/.github/workflows/workflow-validate-repo-markdown.yml +++ b/.github/workflows/workflow-validate-repo-markdown.yml @@ -33,11 +33,10 @@ jobs: with: node-version-file: 'build/.nvmrc' cache: 'npm' - cache-dependency-path: '**/package-lock.json' + cache-dependency-path: 'package-lock.json' - name: Setup Dependencies run: | # NodeJS - cd "${{ github.workspace }}/build" # If you are a developer and need to modify the workflow, be sure to review # the package.json and package-lock.json to ensure the following deps are # at least installed (they will be updated by dependabot): diff --git a/.gitignore b/.gitignore index a87794e09..5ea681914 100644 --- a/.gitignore +++ b/.gitignore @@ -1,13 +1,12 @@ # IDE configuration files *.xpr -# Files generated by Hugo +# Files generated by Hugo and related tools /website/resources /website/public - -# files generated by bundler -/website/.bundle -/website/vendor +/website/.hugo_build.lock +# htmltest +/website/tmp # other generated files @@ -15,4 +14,4 @@ nohup.out /toolchains/xslt-M4/validate/xspec/metaschema-composition-schematron-result.html # Ignore NodeJS modules -node_modules/ \ No newline at end of file +node_modules/ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 0e000e81c..a9d87b753 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -34,7 +34,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at oscal@nist.gov. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at metaschema@nist.gov. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. diff --git a/build/go.mod b/build/go.mod index 39bce64e3..fd065fda3 100644 --- a/build/go.mod +++ b/build/go.mod @@ -1,4 +1,4 @@ -module github.com/usnistgov/OSCAL/build +module github.com/usnistgov/metaschema/build go 1.18 diff --git a/build/package-lock.json b/package-lock.json similarity index 55% rename from build/package-lock.json rename to package-lock.json index e492caa4d..a8bb0355f 100644 --- a/build/package-lock.json +++ b/package-lock.json @@ -10,10 +10,45 @@ "dependencies": { "ajv-cli": "^5.0.x", "ajv-formats": "^2.1.x", + "autoprefixer": "^10.4.14", "markdown-link-check": "^3.10.3", + "postcss": "^8.4.23", + "postcss-cli": "^10.1.0", "yaml-convert": "^1.0.x" } }, + "node_modules/@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "dependencies": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "dependencies": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/@types/color-name": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/@types/color-name/-/color-name-1.1.1.tgz", @@ -98,6 +133,18 @@ "url": "https://github.com/chalk/ansi-styles?sponsor=1" } }, + "node_modules/anymatch": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", + "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", + "dependencies": { + "normalize-path": "^3.0.0", + "picomatch": "^2.0.4" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/argparse": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", @@ -111,11 +158,51 @@ "resolved": "https://registry.npmjs.org/async/-/async-3.2.4.tgz", "integrity": "sha512-iAB+JbDEGXhyIUavoDl9WP/Jj106Kz9DEn1DPgYw5ruDn0e3Wgi3sKFm55sASdGBNOQB8F59d9qQ7deqrHA8wQ==" }, + "node_modules/autoprefixer": { + "version": "10.4.14", + "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.14.tgz", + "integrity": "sha512-FQzyfOsTlwVzjHxKEqRIAdJx9niO6VCBCoEwax/VLSoQF29ggECcPuBqUMZ+u8jCZOPSy8b8/8KnuFbp0SaFZQ==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/autoprefixer" + } + ], + "dependencies": { + "browserslist": "^4.21.5", + "caniuse-lite": "^1.0.30001464", + "fraction.js": "^4.2.0", + "normalize-range": "^0.1.2", + "picocolors": "^1.0.0", + "postcss-value-parser": "^4.2.0" + }, + "bin": { + "autoprefixer": "bin/autoprefixer" + }, + "engines": { + "node": "^10 || ^12 || >=14" + }, + "peerDependencies": { + "postcss": "^8.1.0" + } + }, "node_modules/balanced-match": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==" }, + "node_modules/binary-extensions": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.2.0.tgz", + "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==", + "engines": { + "node": ">=8" + } + }, "node_modules/boolbase": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz", @@ -130,6 +217,63 @@ "concat-map": "0.0.1" } }, + "node_modules/braces": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz", + "integrity": "sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==", + "dependencies": { + "fill-range": "^7.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/browserslist": { + "version": "4.21.5", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.21.5.tgz", + "integrity": "sha512-tUkiguQGW7S3IhB7N+c2MV/HZPSCPAAiYBZXLsBhFB/PCy6ZKKsZrmBayHV9fdGV/ARIfJ14NkxKzRDjvp7L6w==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + } + ], + "dependencies": { + "caniuse-lite": "^1.0.30001449", + "electron-to-chromium": "^1.4.284", + "node-releases": "^2.0.8", + "update-browserslist-db": "^1.0.10" + }, + "bin": { + "browserslist": "cli.js" + }, + "engines": { + "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7" + } + }, + "node_modules/caniuse-lite": { + "version": "1.0.30001487", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001487.tgz", + "integrity": "sha512-83564Z3yWGqXsh2vaH/mhXfEM0wX+NlBCm1jYHOb97TrTWJEmPTccZgeLTPBUUb0PNVo+oomb7wkimZBIERClA==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/caniuse-lite" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ] + }, "node_modules/chalk": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", @@ -181,6 +325,32 @@ "url": "https://github.com/sponsors/fb55" } }, + "node_modules/chokidar": { + "version": "3.5.3", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.5.3.tgz", + "integrity": "sha512-Dr3sfKRP6oTcjf2JmUmFJfeVMvXBdegxB0iVQ5eb2V10uFJUCAS8OByZdVAyVb8xXNz3GjjTgj9kLWsZTqE6kw==", + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ], + "dependencies": { + "anymatch": "~3.1.2", + "braces": "~3.0.2", + "glob-parent": "~5.1.2", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.6.0" + }, + "engines": { + "node": ">= 8.10.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.2" + } + }, "node_modules/cliui": { "version": "7.0.4", "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", @@ -254,6 +424,25 @@ "ms": "^2.1.1" } }, + "node_modules/dependency-graph": { + "version": "0.11.0", + "resolved": "https://registry.npmjs.org/dependency-graph/-/dependency-graph-0.11.0.tgz", + "integrity": "sha512-JeMq7fEshyepOWDfcfHK06N3MhyPhz++vtqWhMT5O9A3K42rdsEDpfdVqjaqaAhsw6a+ZqeDvQVtD0hFHQWrzg==", + "engines": { + "node": ">= 0.6.0" + } + }, + "node_modules/dir-glob": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", + "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", + "dependencies": { + "path-type": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/dom-serializer": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz", @@ -305,6 +494,11 @@ "url": "https://github.com/fb55/domutils?sponsor=1" } }, + "node_modules/electron-to-chromium": { + "version": "1.4.396", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.396.tgz", + "integrity": "sha512-pqKTdqp/c5vsrc0xUPYXTDBo9ixZuGY8es4ZOjjd6HD6bFYbu5QA09VoW3fkY4LF1T0zYk86lN6bZnNlBuOpdQ==" + }, "node_modules/emoji-regex": { "version": "8.0.0", "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", @@ -346,16 +540,88 @@ "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==" }, + "node_modules/fast-glob": { + "version": "3.2.12", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.12.tgz", + "integrity": "sha512-DVj4CQIYYow0BlaelwK1pHl5n5cRSJfM60UA0zK891sVInoPri2Ekj7+e1CT3/3qxXenpI+nBBmQAcJPJgaj4w==", + "dependencies": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.4" + }, + "engines": { + "node": ">=8.6.0" + } + }, "node_modules/fast-json-patch": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/fast-json-patch/-/fast-json-patch-3.1.1.tgz", "integrity": "sha512-vf6IHUX2SBcA+5/+4883dsIjpBTqmfBjmYiWK1savxQmFk4JfBMLa7ynTYOs1Rolp/T1betJxHiGD3g1Mn8lUQ==" }, + "node_modules/fastq": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.15.0.tgz", + "integrity": "sha512-wBrocU2LCXXa+lWBt8RoIRD89Fi8OdABODa/kEnyeyjS5aZO5/GNvI5sEINADqP/h8M29UHTHUb53sUu5Ihqdw==", + "dependencies": { + "reusify": "^1.0.4" + } + }, + "node_modules/fill-range": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz", + "integrity": "sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==", + "dependencies": { + "to-regex-range": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/fraction.js": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-4.2.0.tgz", + "integrity": "sha512-MhLuK+2gUcnZe8ZHlaaINnQLl0xRIGRfcGk2yl8xoQAfHrSsL3rYu6FCmBdkdbhc9EPlwyGHewaRsvwRMJtAlA==", + "engines": { + "node": "*" + }, + "funding": { + "type": "patreon", + "url": "https://www.patreon.com/infusion" + } + }, + "node_modules/fs-extra": { + "version": "11.1.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.1.1.tgz", + "integrity": "sha512-MGIE4HOvQCeUCzmlHs0vXpih4ysz4wg9qiSAu6cd42lVwPbTM1TjV7RusoyQqMmk/95gdQZX72u+YW+c3eEpFQ==", + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^6.0.1", + "universalify": "^2.0.0" + }, + "engines": { + "node": ">=14.14" + } + }, "node_modules/fs.realpath": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=" }, + "node_modules/fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "hasInstallScript": true, + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, "node_modules/get-caller-file": { "version": "2.0.5", "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", @@ -364,6 +630,17 @@ "node": "6.* || 8.* || >= 10.*" } }, + "node_modules/get-stdin": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-9.0.0.tgz", + "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/glob": { "version": "7.2.0", "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz", @@ -383,6 +660,51 @@ "url": "https://github.com/sponsors/isaacs" } }, + "node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/globby": { + "version": "13.1.4", + "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.4.tgz", + "integrity": "sha512-iui/IiiW+QrJ1X1hKH5qwlMQyv34wJAYwH1vrf8b9kBA4sNiif3gKsMHa+BrdnOpEudWjpotfa7LrTzB1ERS/g==", + "dependencies": { + "dir-glob": "^3.0.1", + "fast-glob": "^3.2.11", + "ignore": "^5.2.0", + "merge2": "^1.4.1", + "slash": "^4.0.0" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/globby/node_modules/slash": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-4.0.0.tgz", + "integrity": "sha512-3dOsAHXXUkQTpOYcoAxLIorMTp4gIQr5IW3iVb7A7lFIp0VHhnynm9izx6TssdrIcVIESAlVjtnO2K8bg+Coew==", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==" + }, "node_modules/has-flag": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", @@ -428,6 +750,14 @@ "node": ">=0.10.0" } }, + "node_modules/ignore": { + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz", + "integrity": "sha512-MAb38BcSbH0eHNBxn7ql2NH/kX33OkB3lZ1BNdh7ENeRChHTYsTvWrMubiIAMNS2llXEEgZ1MUOBtXChP3kaFQ==", + "engines": { + "node": ">= 4" + } + }, "node_modules/inflight": { "version": "1.0.6", "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", @@ -453,6 +783,25 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/is-binary-path": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", + "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", + "dependencies": { + "binary-extensions": "^2.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/is-fullwidth-code-point": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", @@ -461,6 +810,25 @@ "node": ">=8" } }, + "node_modules/is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "dependencies": { + "is-extglob": "^2.1.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", + "engines": { + "node": ">=0.12.0" + } + }, "node_modules/is-relative-url": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/is-relative-url/-/is-relative-url-4.0.0.tgz", @@ -522,6 +890,25 @@ "node": ">=6" } }, + "node_modules/jsonfile": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", + "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", + "dependencies": { + "universalify": "^2.0.0" + }, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/lilconfig": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-2.1.0.tgz", + "integrity": "sha512-utWOt/GHzuUxnLKxB6dk81RoOeoNeHgbrXiuGk4yyF5qlRz+iIVWu56E2fqGHFrXz0QNUhLB/8nKqvRH66JKGQ==", + "engines": { + "node": ">=10" + } + }, "node_modules/link-check": { "version": "5.2.0", "resolved": "https://registry.npmjs.org/link-check/-/link-check-5.2.0.tgz", @@ -576,6 +963,26 @@ "node": ">= 12" } }, + "node_modules/merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", + "engines": { + "node": ">= 8" + } + }, + "node_modules/micromatch": { + "version": "4.0.5", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", + "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", + "dependencies": { + "braces": "^3.0.2", + "picomatch": "^2.3.1" + }, + "engines": { + "node": ">=8.6" + } + }, "node_modules/minimatch": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", @@ -597,6 +1004,23 @@ "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==" }, + "node_modules/nanoid": { + "version": "3.3.6", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.6.tgz", + "integrity": "sha512-BGcqMMJuToF7i1rt+2PWSNVnWIkGCU78jBG3RxO/bZlnZPK2Cmi2QaffxGO/2RvWi9sL+FAiRiXMgsyxQ1DIDA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, "node_modules/needle": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/needle/-/needle-3.1.0.tgz", @@ -613,6 +1037,27 @@ "node": ">= 4.4.x" } }, + "node_modules/node-releases": { + "version": "2.0.10", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.10.tgz", + "integrity": "sha512-5GFldHPXVG/YZmFzJvKK2zDSzPKhEp0+ZR5SVaoSag9fsL5YgHbUHDfnG5494ISANDcK4KwPXAx2xqVEydmd7w==" + }, + "node_modules/normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/normalize-range": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/normalize-range/-/normalize-range-0.1.2.tgz", + "integrity": "sha512-bdok/XvKII3nUpklnV6P2hxtMNrCboOjAcyBuQnWEhO665FwrSNRxU+AqpsyvO6LgGYPspN+lu5CLtw4jPRKNA==", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/nth-check": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", @@ -663,6 +1108,161 @@ "node": ">=0.10.0" } }, + "node_modules/path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", + "engines": { + "node": ">=8" + } + }, + "node_modules/picocolors": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz", + "integrity": "sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ==" + }, + "node_modules/picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/postcss": { + "version": "8.4.23", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.23.tgz", + "integrity": "sha512-bQ3qMcpF6A/YjR55xtoTr0jGOlnPOKAIMdOWiv0EIT6HVPEaJiJB4NLljSbiHoC2RX7DN5Uvjtpbg1NPdwv1oA==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "dependencies": { + "nanoid": "^3.3.6", + "picocolors": "^1.0.0", + "source-map-js": "^1.0.2" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/postcss-cli": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/postcss-cli/-/postcss-cli-10.1.0.tgz", + "integrity": "sha512-Zu7PLORkE9YwNdvOeOVKPmWghprOtjFQU3srMUGbdz3pHJiFh7yZ4geiZFMkjMfB0mtTFR3h8RemR62rPkbOPA==", + "dependencies": { + "chokidar": "^3.3.0", + "dependency-graph": "^0.11.0", + "fs-extra": "^11.0.0", + "get-stdin": "^9.0.0", + "globby": "^13.0.0", + "picocolors": "^1.0.0", + "postcss-load-config": "^4.0.0", + "postcss-reporter": "^7.0.0", + "pretty-hrtime": "^1.0.3", + "read-cache": "^1.0.0", + "slash": "^5.0.0", + "yargs": "^17.0.0" + }, + "bin": { + "postcss": "index.js" + }, + "engines": { + "node": ">=14" + }, + "peerDependencies": { + "postcss": "^8.0.0" + } + }, + "node_modules/postcss-load-config": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-4.0.1.tgz", + "integrity": "sha512-vEJIc8RdiBRu3oRAI0ymerOn+7rPuMvRXslTvZUKZonDHFIczxztIyJ1urxM1x9JXEikvpWWTUUqal5j/8QgvA==", + "dependencies": { + "lilconfig": "^2.0.5", + "yaml": "^2.1.1" + }, + "engines": { + "node": ">= 14" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + "peerDependencies": { + "postcss": ">=8.0.9", + "ts-node": ">=9.0.0" + }, + "peerDependenciesMeta": { + "postcss": { + "optional": true + }, + "ts-node": { + "optional": true + } + } + }, + "node_modules/postcss-load-config/node_modules/yaml": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.2.2.tgz", + "integrity": "sha512-CBKFWExMn46Foo4cldiChEzn7S7SRV+wqiluAb6xmueD/fGyRHIhX8m14vVGgeFWjN540nKCNVj6P21eQjgTuA==", + "engines": { + "node": ">= 14" + } + }, + "node_modules/postcss-reporter": { + "version": "7.0.5", + "resolved": "https://registry.npmjs.org/postcss-reporter/-/postcss-reporter-7.0.5.tgz", + "integrity": "sha512-glWg7VZBilooZGOFPhN9msJ3FQs19Hie7l5a/eE6WglzYqVeH3ong3ShFcp9kDWJT1g2Y/wd59cocf9XxBtkWA==", + "dependencies": { + "picocolors": "^1.0.0", + "thenby": "^1.3.4" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + "peerDependencies": { + "postcss": "^8.1.0" + } + }, + "node_modules/postcss-value-parser": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", + "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==" + }, + "node_modules/pretty-hrtime": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz", + "integrity": "sha512-66hKPCr+72mlfiSjlEB1+45IjXSqvVAIy6mocupoww4tBFE9R9IhwwUGoI4G++Tc9Aq+2rxOt0RFU6gPcrte0A==", + "engines": { + "node": ">= 0.8" + } + }, "node_modules/progress": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz", @@ -679,6 +1279,44 @@ "node": ">=6" } }, + "node_modules/queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ] + }, + "node_modules/read-cache": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz", + "integrity": "sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==", + "dependencies": { + "pify": "^2.3.0" + } + }, + "node_modules/readdirp": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", + "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", + "dependencies": { + "picomatch": "^2.2.1" + }, + "engines": { + "node": ">=8.10.0" + } + }, "node_modules/require-directory": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", @@ -695,6 +1333,37 @@ "node": ">=0.10.0" } }, + "node_modules/reusify": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz", + "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==", + "engines": { + "iojs": ">=1.0.0", + "node": ">=0.10.0" + } + }, + "node_modules/run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "dependencies": { + "queue-microtask": "^1.2.2" + } + }, "node_modules/safer-buffer": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", @@ -705,6 +1374,25 @@ "resolved": "https://registry.npmjs.org/sax/-/sax-1.2.4.tgz", "integrity": "sha512-NqVDv9TpANUjFm0N8uM5GxL36UgKi9/atZw+x7YFnQ8ckwFGKrl4xX4yWtrey3UJm5nP1kUbnYgLopqWNSRhWw==" }, + "node_modules/slash": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz", + "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==", + "engines": { + "node": ">=14.16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/source-map-js": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.0.2.tgz", + "integrity": "sha512-R0XvVJ9WusLiqTCEiGCmICCMplcCkIwwR11mOSD9CR5u+IXYdiseeEuXCVAjS54zqwkLcPNnmU4OeJ6tUrWhDw==", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/sprintf-js": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", @@ -745,6 +1433,59 @@ "node": ">=8" } }, + "node_modules/thenby": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/thenby/-/thenby-1.3.4.tgz", + "integrity": "sha512-89Gi5raiWA3QZ4b2ePcEwswC3me9JIg+ToSgtE0JWeCynLnLxNr/f9G+xfo9K+Oj4AFdom8YNJjibIARTJmapQ==" + }, + "node_modules/to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "dependencies": { + "is-number": "^7.0.0" + }, + "engines": { + "node": ">=8.0" + } + }, + "node_modules/universalify": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.0.tgz", + "integrity": "sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==", + "engines": { + "node": ">= 10.0.0" + } + }, + "node_modules/update-browserslist-db": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.11.tgz", + "integrity": "sha512-dCwEFf0/oT85M1fHBg4F0jtLwJrutGoHSQXCh7u4o2t1drG+c0a9Flnqww6XUKSfQMPpJBRjU8d4RXB09qtvaA==", + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/browserslist" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/browserslist" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "dependencies": { + "escalade": "^3.1.1", + "picocolors": "^1.0.0" + }, + "bin": { + "update-browserslist-db": "cli.js" + }, + "peerDependencies": { + "browserslist": ">= 4.21.0" + } + }, "node_modules/uri-js": { "version": "4.4.1", "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", @@ -830,6 +1571,29 @@ } }, "dependencies": { + "@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "requires": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + } + }, + "@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==" + }, + "@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "requires": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + } + }, "@types/color-name": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/@types/color-name/-/color-name-1.1.1.tgz", @@ -882,6 +1646,15 @@ "color-convert": "^2.0.1" } }, + "anymatch": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz", + "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==", + "requires": { + "normalize-path": "^3.0.0", + "picomatch": "^2.0.4" + } + }, "argparse": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", @@ -895,11 +1668,29 @@ "resolved": "https://registry.npmjs.org/async/-/async-3.2.4.tgz", "integrity": "sha512-iAB+JbDEGXhyIUavoDl9WP/Jj106Kz9DEn1DPgYw5ruDn0e3Wgi3sKFm55sASdGBNOQB8F59d9qQ7deqrHA8wQ==" }, + "autoprefixer": { + "version": "10.4.14", + "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.14.tgz", + "integrity": "sha512-FQzyfOsTlwVzjHxKEqRIAdJx9niO6VCBCoEwax/VLSoQF29ggECcPuBqUMZ+u8jCZOPSy8b8/8KnuFbp0SaFZQ==", + "requires": { + "browserslist": "^4.21.5", + "caniuse-lite": "^1.0.30001464", + "fraction.js": "^4.2.0", + "normalize-range": "^0.1.2", + "picocolors": "^1.0.0", + "postcss-value-parser": "^4.2.0" + } + }, "balanced-match": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==" }, + "binary-extensions": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.2.0.tgz", + "integrity": "sha512-jDctJ/IVQbZoJykoeHbhXpOlNBqGNcwXJKJog42E5HDPUwQTSdjCHdihjj0DlnheQ7blbT6dHOafNAiS8ooQKA==" + }, "boolbase": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz", @@ -914,6 +1705,30 @@ "concat-map": "0.0.1" } }, + "braces": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.2.tgz", + "integrity": "sha512-b8um+L1RzM3WDSzvhm6gIz1yfTbBt6YTlcEKAvsmqCZZFw46z626lVj9j1yEPW33H5H+lBQpZMP1k8l+78Ha0A==", + "requires": { + "fill-range": "^7.0.1" + } + }, + "browserslist": { + "version": "4.21.5", + "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.21.5.tgz", + "integrity": "sha512-tUkiguQGW7S3IhB7N+c2MV/HZPSCPAAiYBZXLsBhFB/PCy6ZKKsZrmBayHV9fdGV/ARIfJ14NkxKzRDjvp7L6w==", + "requires": { + "caniuse-lite": "^1.0.30001449", + "electron-to-chromium": "^1.4.284", + "node-releases": "^2.0.8", + "update-browserslist-db": "^1.0.10" + } + }, + "caniuse-lite": { + "version": "1.0.30001487", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001487.tgz", + "integrity": "sha512-83564Z3yWGqXsh2vaH/mhXfEM0wX+NlBCm1jYHOb97TrTWJEmPTccZgeLTPBUUb0PNVo+oomb7wkimZBIERClA==" + }, "chalk": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", @@ -950,6 +1765,21 @@ "domutils": "^3.0.1" } }, + "chokidar": { + "version": "3.5.3", + "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.5.3.tgz", + "integrity": "sha512-Dr3sfKRP6oTcjf2JmUmFJfeVMvXBdegxB0iVQ5eb2V10uFJUCAS8OByZdVAyVb8xXNz3GjjTgj9kLWsZTqE6kw==", + "requires": { + "anymatch": "~3.1.2", + "braces": "~3.0.2", + "fsevents": "~2.3.2", + "glob-parent": "~5.1.2", + "is-binary-path": "~2.1.0", + "is-glob": "~4.0.1", + "normalize-path": "~3.0.0", + "readdirp": "~3.6.0" + } + }, "cliui": { "version": "7.0.4", "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz", @@ -1008,6 +1838,19 @@ "ms": "^2.1.1" } }, + "dependency-graph": { + "version": "0.11.0", + "resolved": "https://registry.npmjs.org/dependency-graph/-/dependency-graph-0.11.0.tgz", + "integrity": "sha512-JeMq7fEshyepOWDfcfHK06N3MhyPhz++vtqWhMT5O9A3K42rdsEDpfdVqjaqaAhsw6a+ZqeDvQVtD0hFHQWrzg==" + }, + "dir-glob": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", + "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", + "requires": { + "path-type": "^4.0.0" + } + }, "dom-serializer": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz", @@ -1041,6 +1884,11 @@ "domhandler": "^5.0.1" } }, + "electron-to-chromium": { + "version": "1.4.396", + "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.4.396.tgz", + "integrity": "sha512-pqKTdqp/c5vsrc0xUPYXTDBo9ixZuGY8es4ZOjjd6HD6bFYbu5QA09VoW3fkY4LF1T0zYk86lN6bZnNlBuOpdQ==" + }, "emoji-regex": { "version": "8.0.0", "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", @@ -1066,21 +1914,75 @@ "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==" }, + "fast-glob": { + "version": "3.2.12", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.2.12.tgz", + "integrity": "sha512-DVj4CQIYYow0BlaelwK1pHl5n5cRSJfM60UA0zK891sVInoPri2Ekj7+e1CT3/3qxXenpI+nBBmQAcJPJgaj4w==", + "requires": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.4" + } + }, "fast-json-patch": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/fast-json-patch/-/fast-json-patch-3.1.1.tgz", "integrity": "sha512-vf6IHUX2SBcA+5/+4883dsIjpBTqmfBjmYiWK1savxQmFk4JfBMLa7ynTYOs1Rolp/T1betJxHiGD3g1Mn8lUQ==" }, + "fastq": { + "version": "1.15.0", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.15.0.tgz", + "integrity": "sha512-wBrocU2LCXXa+lWBt8RoIRD89Fi8OdABODa/kEnyeyjS5aZO5/GNvI5sEINADqP/h8M29UHTHUb53sUu5Ihqdw==", + "requires": { + "reusify": "^1.0.4" + } + }, + "fill-range": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.0.1.tgz", + "integrity": "sha512-qOo9F+dMUmC2Lcb4BbVvnKJxTPjCm+RRpe4gDuGrzkL7mEVl/djYSu2OdQ2Pa302N4oqkSg9ir6jaLWJ2USVpQ==", + "requires": { + "to-regex-range": "^5.0.1" + } + }, + "fraction.js": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-4.2.0.tgz", + "integrity": "sha512-MhLuK+2gUcnZe8ZHlaaINnQLl0xRIGRfcGk2yl8xoQAfHrSsL3rYu6FCmBdkdbhc9EPlwyGHewaRsvwRMJtAlA==" + }, + "fs-extra": { + "version": "11.1.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.1.1.tgz", + "integrity": "sha512-MGIE4HOvQCeUCzmlHs0vXpih4ysz4wg9qiSAu6cd42lVwPbTM1TjV7RusoyQqMmk/95gdQZX72u+YW+c3eEpFQ==", + "requires": { + "graceful-fs": "^4.2.0", + "jsonfile": "^6.0.1", + "universalify": "^2.0.0" + } + }, "fs.realpath": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", "integrity": "sha1-FQStJSMVjKpA20onh8sBQRmU6k8=" }, + "fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "optional": true + }, "get-caller-file": { "version": "2.0.5", "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==" }, + "get-stdin": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-9.0.0.tgz", + "integrity": "sha512-dVKBjfWisLAicarI2Sf+JuBE/DghV4UzNAVe9yhEJuzeREd3JhOTE9cUaJTeSa77fsbQUK3pcOpJfM59+VKZaA==" + }, "glob": { "version": "7.2.0", "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.0.tgz", @@ -1094,6 +1996,38 @@ "path-is-absolute": "^1.0.0" } }, + "glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "requires": { + "is-glob": "^4.0.1" + } + }, + "globby": { + "version": "13.1.4", + "resolved": "https://registry.npmjs.org/globby/-/globby-13.1.4.tgz", + "integrity": "sha512-iui/IiiW+QrJ1X1hKH5qwlMQyv34wJAYwH1vrf8b9kBA4sNiif3gKsMHa+BrdnOpEudWjpotfa7LrTzB1ERS/g==", + "requires": { + "dir-glob": "^3.0.1", + "fast-glob": "^3.2.11", + "ignore": "^5.2.0", + "merge2": "^1.4.1", + "slash": "^4.0.0" + }, + "dependencies": { + "slash": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-4.0.0.tgz", + "integrity": "sha512-3dOsAHXXUkQTpOYcoAxLIorMTp4gIQr5IW3iVb7A7lFIp0VHhnynm9izx6TssdrIcVIESAlVjtnO2K8bg+Coew==" + } + } + }, + "graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==" + }, "has-flag": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", @@ -1126,6 +2060,11 @@ "safer-buffer": ">= 2.1.2 < 3.0.0" } }, + "ignore": { + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz", + "integrity": "sha512-MAb38BcSbH0eHNBxn7ql2NH/kX33OkB3lZ1BNdh7ENeRChHTYsTvWrMubiIAMNS2llXEEgZ1MUOBtXChP3kaFQ==" + }, "inflight": { "version": "1.0.6", "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz", @@ -1145,11 +2084,37 @@ "resolved": "https://registry.npmjs.org/is-absolute-url/-/is-absolute-url-4.0.1.tgz", "integrity": "sha512-/51/TKE88Lmm7Gc4/8btclNXWS+g50wXhYJq8HWIBAGUBnoAdRu1aXeh364t/O7wXDAcTJDP8PNuNKWUDWie+A==" }, + "is-binary-path": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz", + "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==", + "requires": { + "binary-extensions": "^2.0.0" + } + }, + "is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==" + }, "is-fullwidth-code-point": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==" }, + "is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "requires": { + "is-extglob": "^2.1.1" + } + }, + "is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==" + }, "is-relative-url": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/is-relative-url/-/is-relative-url-4.0.0.tgz", @@ -1193,6 +2158,20 @@ "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz", "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==" }, + "jsonfile": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz", + "integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==", + "requires": { + "graceful-fs": "^4.1.6", + "universalify": "^2.0.0" + } + }, + "lilconfig": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-2.1.0.tgz", + "integrity": "sha512-utWOt/GHzuUxnLKxB6dk81RoOeoNeHgbrXiuGk4yyF5qlRz+iIVWu56E2fqGHFrXz0QNUhLB/8nKqvRH66JKGQ==" + }, "link-check": { "version": "5.2.0", "resolved": "https://registry.npmjs.org/link-check/-/link-check-5.2.0.tgz", @@ -1238,6 +2217,20 @@ "resolved": "https://registry.npmjs.org/marked/-/marked-4.1.0.tgz", "integrity": "sha512-+Z6KDjSPa6/723PQYyc1axYZpYYpDnECDaU6hkaf5gqBieBkMKYReL5hteF2QizhlMbgbo8umXl/clZ67+GlsA==" }, + "merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==" + }, + "micromatch": { + "version": "4.0.5", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", + "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", + "requires": { + "braces": "^3.0.2", + "picomatch": "^2.3.1" + } + }, "minimatch": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", @@ -1256,6 +2249,11 @@ "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==" }, + "nanoid": { + "version": "3.3.6", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.6.tgz", + "integrity": "sha512-BGcqMMJuToF7i1rt+2PWSNVnWIkGCU78jBG3RxO/bZlnZPK2Cmi2QaffxGO/2RvWi9sL+FAiRiXMgsyxQ1DIDA==" + }, "needle": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/needle/-/needle-3.1.0.tgz", @@ -1266,6 +2264,21 @@ "sax": "^1.2.4" } }, + "node-releases": { + "version": "2.0.10", + "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.10.tgz", + "integrity": "sha512-5GFldHPXVG/YZmFzJvKK2zDSzPKhEp0+ZR5SVaoSag9fsL5YgHbUHDfnG5494ISANDcK4KwPXAx2xqVEydmd7w==" + }, + "normalize-path": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz", + "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==" + }, + "normalize-range": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/normalize-range/-/normalize-range-0.1.2.tgz", + "integrity": "sha512-bdok/XvKII3nUpklnV6P2hxtMNrCboOjAcyBuQnWEhO665FwrSNRxU+AqpsyvO6LgGYPspN+lu5CLtw4jPRKNA==" + }, "nth-check": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz", @@ -1304,6 +2317,90 @@ "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz", "integrity": "sha1-F0uSaHNVNP+8es5r9TpanhtcX18=" }, + "path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==" + }, + "picocolors": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.0.0.tgz", + "integrity": "sha512-1fygroTLlHu66zi26VoTDv8yRgm0Fccecssto+MhsZ0D/DGW2sm8E8AjW7NU5VVTRt5GxbeZ5qBuJr+HyLYkjQ==" + }, + "picomatch": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", + "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==" + }, + "pify": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", + "integrity": "sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==" + }, + "postcss": { + "version": "8.4.23", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.23.tgz", + "integrity": "sha512-bQ3qMcpF6A/YjR55xtoTr0jGOlnPOKAIMdOWiv0EIT6HVPEaJiJB4NLljSbiHoC2RX7DN5Uvjtpbg1NPdwv1oA==", + "requires": { + "nanoid": "^3.3.6", + "picocolors": "^1.0.0", + "source-map-js": "^1.0.2" + } + }, + "postcss-cli": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/postcss-cli/-/postcss-cli-10.1.0.tgz", + "integrity": "sha512-Zu7PLORkE9YwNdvOeOVKPmWghprOtjFQU3srMUGbdz3pHJiFh7yZ4geiZFMkjMfB0mtTFR3h8RemR62rPkbOPA==", + "requires": { + "chokidar": "^3.3.0", + "dependency-graph": "^0.11.0", + "fs-extra": "^11.0.0", + "get-stdin": "^9.0.0", + "globby": "^13.0.0", + "picocolors": "^1.0.0", + "postcss-load-config": "^4.0.0", + "postcss-reporter": "^7.0.0", + "pretty-hrtime": "^1.0.3", + "read-cache": "^1.0.0", + "slash": "^5.0.0", + "yargs": "^17.0.0" + } + }, + "postcss-load-config": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-4.0.1.tgz", + "integrity": "sha512-vEJIc8RdiBRu3oRAI0ymerOn+7rPuMvRXslTvZUKZonDHFIczxztIyJ1urxM1x9JXEikvpWWTUUqal5j/8QgvA==", + "requires": { + "lilconfig": "^2.0.5", + "yaml": "^2.1.1" + }, + "dependencies": { + "yaml": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.2.2.tgz", + "integrity": "sha512-CBKFWExMn46Foo4cldiChEzn7S7SRV+wqiluAb6xmueD/fGyRHIhX8m14vVGgeFWjN540nKCNVj6P21eQjgTuA==" + } + } + }, + "postcss-reporter": { + "version": "7.0.5", + "resolved": "https://registry.npmjs.org/postcss-reporter/-/postcss-reporter-7.0.5.tgz", + "integrity": "sha512-glWg7VZBilooZGOFPhN9msJ3FQs19Hie7l5a/eE6WglzYqVeH3ong3ShFcp9kDWJT1g2Y/wd59cocf9XxBtkWA==", + "requires": { + "picocolors": "^1.0.0", + "thenby": "^1.3.4" + } + }, + "postcss-value-parser": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", + "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==" + }, + "pretty-hrtime": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz", + "integrity": "sha512-66hKPCr+72mlfiSjlEB1+45IjXSqvVAIy6mocupoww4tBFE9R9IhwwUGoI4G++Tc9Aq+2rxOt0RFU6gPcrte0A==" + }, "progress": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz", @@ -1314,6 +2411,27 @@ "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.1.1.tgz", "integrity": "sha512-XRsRjdf+j5ml+y/6GKHPZbrF/8p2Yga0JPtdqTIY2Xe5ohJPD9saDJJLPvp9+NSBprVvevdXZybnj2cv8OEd0A==" }, + "queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==" + }, + "read-cache": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz", + "integrity": "sha512-Owdv/Ft7IjOgm/i0xvNDZ1LrRANRfew4b2prF3OWMQLxLfu3bS8FVhCsrSCMK4lR56Y9ya+AThoTpDCTxCmpRA==", + "requires": { + "pify": "^2.3.0" + } + }, + "readdirp": { + "version": "3.6.0", + "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", + "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==", + "requires": { + "picomatch": "^2.2.1" + } + }, "require-directory": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", @@ -1324,6 +2442,19 @@ "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==" }, + "reusify": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz", + "integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==" + }, + "run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "requires": { + "queue-microtask": "^1.2.2" + } + }, "safer-buffer": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", @@ -1334,6 +2465,16 @@ "resolved": "https://registry.npmjs.org/sax/-/sax-1.2.4.tgz", "integrity": "sha512-NqVDv9TpANUjFm0N8uM5GxL36UgKi9/atZw+x7YFnQ8ckwFGKrl4xX4yWtrey3UJm5nP1kUbnYgLopqWNSRhWw==" }, + "slash": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz", + "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==" + }, + "source-map-js": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.0.2.tgz", + "integrity": "sha512-R0XvVJ9WusLiqTCEiGCmICCMplcCkIwwR11mOSD9CR5u+IXYdiseeEuXCVAjS54zqwkLcPNnmU4OeJ6tUrWhDw==" + }, "sprintf-js": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", @@ -1365,6 +2506,33 @@ "has-flag": "^4.0.0" } }, + "thenby": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/thenby/-/thenby-1.3.4.tgz", + "integrity": "sha512-89Gi5raiWA3QZ4b2ePcEwswC3me9JIg+ToSgtE0JWeCynLnLxNr/f9G+xfo9K+Oj4AFdom8YNJjibIARTJmapQ==" + }, + "to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "requires": { + "is-number": "^7.0.0" + } + }, + "universalify": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.0.tgz", + "integrity": "sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==" + }, + "update-browserslist-db": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.11.tgz", + "integrity": "sha512-dCwEFf0/oT85M1fHBg4F0jtLwJrutGoHSQXCh7u4o2t1drG+c0a9Flnqww6XUKSfQMPpJBRjU8d4RXB09qtvaA==", + "requires": { + "escalade": "^3.1.1", + "picocolors": "^1.0.0" + } + }, "uri-js": { "version": "4.4.1", "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz", diff --git a/build/package.json b/package.json similarity index 73% rename from build/package.json rename to package.json index ce908a2d1..e11a18ce1 100644 --- a/build/package.json +++ b/package.json @@ -4,10 +4,13 @@ "dependencies": { "ajv-cli": "^5.0.x", "ajv-formats": "^2.1.x", + "autoprefixer": "^10.4.14", "markdown-link-check": "^3.10.3", + "postcss": "^8.4.23", + "postcss-cli": "^10.1.0", "yaml-convert": "^1.0.x" }, "overrides": { "fast-json-patch": "^3.1.1" } -} +} diff --git a/schema/json/metaschema-datatypes.json b/schema/json/metaschema-datatypes.json index e1ac4ccab..e76ccacbe 100644 --- a/schema/json/metaschema-datatypes.json +++ b/schema/json/metaschema-datatypes.json @@ -1,44 +1,53 @@ { "$schema" : "http://json-schema.org/draft-07/schema#", "$id" : "http://csrc.nist.gov/ns/oscal/1.0/metaschema-datatypes-schema.json", - "$comment" : "OSCAL Unified Model of Models", + "$comment" : "Metaschema JSON data types", "type" : "object", "definitions" : { "Base64Datatype": { + "description": "Binary data encoded using the Base 64 encoding algorithm as defined by RFC4648.", "type": "string", "pattern": "^[0-9A-Za-z+\/]+={0,2}$", "contentEncoding": "base64" }, "BooleanDatatype": { + "description": "A binary value that is either: true or false.", "type": "boolean" }, "DateDatatype": { + "description": "A string representing a 24-hour period with an optional timezone.", "type": "string", "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))(Z|[+-][0-9]{2}:[0-9]{2})?$" }, "DateWithTimezoneDatatype": { + "description": "A string representing a 24-hour period with a required timezone.", "type": "string", "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))(Z|[+-][0-9]{2}:[0-9]{2})$" }, "DateTimeDatatype": { + "description": "A string representing a point in time with an optional timezone.", "type": "string", "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]*[1-9])?(Z|(-((0[0-9]|1[0-2]):00|0[39]:30)|\\+((0[0-9]|1[0-4]):00|(0[34569]|10):30|(0[58]|12):45)))?$" }, "DateTimeWithTimezoneDatatype": { + "description": "A string representing a point in time with a required timezone.", "type": "string", "format": "date-time", "pattern": "^(((2000|2400|2800|(19|2[0-9](0[48]|[2468][048]|[13579][26])))-02-29)|(((19|2[0-9])[0-9]{2})-02-(0[1-9]|1[0-9]|2[0-8]))|(((19|2[0-9])[0-9]{2})-(0[13578]|10|12)-(0[1-9]|[12][0-9]|3[01]))|(((19|2[0-9])[0-9]{2})-(0[469]|11)-(0[1-9]|[12][0-9]|30)))T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]*[1-9])?(Z|(-((0[0-9]|1[0-2]):00|0[39]:30)|\\+((0[0-9]|1[0-4]):00|(0[34569]|10):30|(0[58]|12):45)))$" }, "DayTimeDurationDatatype": { + "description": "An amount of time quantified in days, hours, minutes, and seconds.", "type": "string", "format": "duration", "pattern": "^-?P([0-9]+D(T(([0-9]+H([0-9]+M)?(([0-9]+|[0-9]+(\\.[0-9]+)?)S)?)|([0-9]+M(([0-9]+|[0-9]+(\\.[0-9]+)?)S)?)|([0-9]+|[0-9]+(\\.[0-9]+)?)S))?)|T(([0-9]+H([0-9]+M)?(([0-9]+|[0-9]+(\\.[0-9]+)?)S)?)|([0-9]+M(([0-9]+|[0-9]+(\\.[0-9]+)?)S)?)|([0-9]+|[0-9]+(\\.[0-9]+)?)S)$" }, "DecimalDatatype": { + "description": "A real number expressed using a whole and optional fractional part separated by a period.", "type": "number", "pattern": "^(\\+|-)?([0-9]+(\\.[0-9]*)?|\\.[0-9]+)$" }, "EmailAddressDatatype": { + "description": "An email address string formatted according to RFC 6531.", "allOf": [ {"$ref": "#/definitions/StringDatatype"}, { @@ -46,9 +55,10 @@ "format": "email", "pattern": "^.+@.+$" } - ] + ] }, "HostnameDatatype": { + "description": "An internationalized Internet host name string formatted according to section 2.3.2.3 of RFC5890.", "allOf": [ {"$ref": "#/definitions/StringDatatype"}, { @@ -58,26 +68,32 @@ ] }, "IntegerDatatype": { + "description": "A whole number value.", "type": "integer" }, "IPV4AddressDatatype": { + "description": "An Internet Protocol version 4 address represented using dotted-quad syntax as defined in section 3.2 of RFC2673.", "type": "string", "format": "ipv4", "pattern": "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, "IPV6AddressDatatype": { + "description": "An Internet Protocol version 6 address represented using the syntax defined in section 2.2 of RFC3513.", "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|[fF][eE]80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::([fF]{4}(:0{1,4}){0,1}:){0,1}((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9]).){3,3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9]).){3,3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9]))$" }, "MarkupLineDatatype": { + "description": "A single line of Markdown content conformant to the Commonmark specification.", "type": "string", "pattern": "^[^\n]+$" }, "MarkupMultilineDatatype": { + "description": "A multiple lines of Markdown content conformant to the Commonmark specification.", "type": "string" }, "NonNegativeIntegerDatatype": { + "description": "An integer value that is equal to or greater than 0.", "allOf": [ {"$ref": "#/definitions/IntegerDatatype"}, { @@ -87,6 +103,7 @@ ] }, "PositiveIntegerDatatype": { + "description": "An integer value that is greater than 0.", "allOf": [ {"$ref": "#/definitions/IntegerDatatype"}, { @@ -96,28 +113,33 @@ ] }, "StringDatatype": { + "description": "A non-empty string with leading and trailing whitespace disallowed. Whitespace is: U+9, U+10, U+32 or [ \n\t]+", "type": "string", "pattern": "^\\S(.*\\S)?$" }, "TokenDatatype": { + "description": "A non-colonized name as defined by XML Schema Part 2: Datatypes Second Edition. https://www.w3.org/TR/xmlschema11-2/#NCName.", "type": "string", "pattern": "^(\\p{L}|_)(\\p{L}|\\p{N}|[.\\-_])*$" }, "URIDatatype": { + "description": "A universal resource identifier (URI) formatted according to RFC3986.", "type": "string", "format": "uri", "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]+:.+$" }, "URIReferenceDatatype": { + "description": "A URI Reference, either a URI or a relative-reference, formatted according to section 4.1 of RFC3986.", "type": "string", "format": "uri-reference" }, "UUIDDatatype": { - "type": "string", "description": "A type 4 ('random' or 'pseudorandom') or type 5 UUID per RFC 4122.", + "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[45][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$" }, "YearMonthDurationDatatype": { + "description": "An amount of time quantified in years and months based on ISO-8601 durations (see also RFC3339 appendix A).", "type": "string", "format": "duration", "pattern": "^-?P([0-9]+Y([0-9]+M)?)|[0-9]+M$" diff --git a/schema/xml/metaschema-datatypes.xsd b/schema/xml/metaschema-datatypes.xsd index 7d1b4e46c..bcb95087d 100644 --- a/schema/xml/metaschema-datatypes.xsd +++ b/schema/xml/metaschema-datatypes.xsd @@ -3,18 +3,28 @@ elementFormDefault="qualified"> + + Binary data encoded using the Base64 encoding algorithm + as defined by RFC4648. + + + A binary value that is either: true (or 1) or false (or 0). + + + A string representing a 24-hour period with an optional timezone. + @@ -22,7 +32,7 @@ - The xs:date with a required timezone. + A string representing a 24-hour period with a required timezone. @@ -30,6 +40,9 @@ + + A string representing a point in time with an optional timezone. + @@ -37,7 +50,7 @@ - The xs:dateTime with a required timezone. + A string representing a point in time with a required timezone. @@ -45,17 +58,25 @@ + + An amount of time quantified in days, hours, minutes, and seconds. + + + A real number expressed using a whole and optional fractional part + separated by a period. + - A trimmed string, at least one character with no - leading or trailing whitespace. + This pattern ensures that leading and trailing whitespace is + disallowed. This helps to even the user experience between implementations + related to whitespace. @@ -63,13 +84,11 @@ - An email address + An email address string formatted according to RFC 6531. - - Need a better pattern. - + @@ -84,11 +103,15 @@ + + A whole number value. + - A trimmed string, at least one character with no - leading or trailing whitespace. + This pattern ensures that leading and trailing whitespace is + disallowed. This helps to even the user experience between implementations + related to whitespace. @@ -96,8 +119,8 @@ - The ip-v4-address type specifies an IPv4 address in - dot decimal notation. + An Internet Protocol version 4 address represented using + dotted-quad syntax as defined in section 3.2 of RFC2673. @@ -106,36 +129,43 @@ - The ip-v6-address type specifies an IPv6 address - represented in 8 hextets separated by colons. + An Internet Protocol version 6 address represented using + the syntax defined in section 2.2 of RFC3513. This is based on the pattern provided here: https://stackoverflow.com/questions/53497/regular-expression-that-matches-valid-ipv6-addresses with some customizations. - - + + + An integer value that is equal to or greater than 0. + - A trimmed string, at least one character with no - leading or trailing whitespace. + This pattern ensures that leading and trailing whitespace is + disallowed. This helps to even the user experience between implementations + related to whitespace. + + An integer value that is greater than 0. + - A trimmed string, at least one character with no - leading or trailing whitespace. + This pattern ensures that leading and trailing whitespace is + disallowed. This helps to even the user experience between implementations + related to whitespace. @@ -143,19 +173,20 @@ - A string, but not empty and not whitespace-only - (whitespace is U+9, U+10, U+32 or [ \n\t]+ ) + A non-empty string of Unicode characters with leading and trailing whitespace + disallowed. Whitespace is: U+9, U+10, U+32 or [ \n\t]+ - The OSCAL 'string' datatype restricts the XSD type by prohibiting leading + The 'string' datatype restricts the XSD type by prohibiting leading and trailing whitespace, and something (not only whitespace) is required. - A trimmed string, at least one character with no - leading or trailing whitespace. + This pattern ensures that leading and trailing whitespace is + disallowed. This helps to even the user experience between implementations + related to whitespace. @@ -164,15 +195,12 @@ - A string token following the rules of XML "no - colon" names, with no whitespace. (XML names are single alphabetic - characters followed by alphanumeric characters, periods, underscores or dashes.) - + A non-empty, non-colonized name as defined by XML Schema Part 2: Datatypes + Second Edition (https://www.w3.org/TR/xmlschema11-2/#NCName), with leading and trailing + whitespace disallowed. - - + @@ -185,7 +213,7 @@ - A URI + A universal resource identifier (URI) formatted according to RFC3986. @@ -198,14 +226,14 @@ - A URI reference, such as a relative URL - + A URI Reference, either a URI or a relative-reference, formatted according to section 4.1 of RFC3986. - A trimmed URI, at least one character with no - leading or trailing whitespace. + This pattern ensures that leading and trailing whitespace is + disallowed. This helps to even the user experience between implementations + related to whitespace. @@ -217,8 +245,7 @@ 4122. - + A sequence of 8-4-4-4-12 hex digits, with extra constraints in the 13th and 17-18th places for version 4 and 5 diff --git a/schema/xml/metaschema.xsd b/schema/xml/metaschema.xsd index 6ac0e4787..aa1a83536 100644 --- a/schema/xml/metaschema.xsd +++ b/schema/xml/metaschema.xsd @@ -17,12 +17,9 @@ - - - Root element of an OSCAL Metaschema definition. Defines a family of data + Root element of a Metaschema definition. Defines a family of data structures representing a model. @@ -36,12 +33,12 @@ - The namespace for the collection of Metaschema models this Metaschema definition + The namespace for the collection of Metaschema models this Metaschema module belongs to. Also the XML namespace governing the names of elements in XML documents, which expect to be conformant to the schemas expressed by this metaschema. By using this namespace, documents and document fragments used in mixed-format environments may be distinguished from neighbor XML formats using other namespaces. This value is not reflected in - OSCAL JSON. + Metaschema JSON. @@ -74,7 +71,7 @@ - Root element of an OSCAL Metaschema external constraints definition. Defines rules to be applied to an existing set of Metaschema models. + Root element of a Metaschema external constraints definition. Defines rules to be applied to an existing set of Metaschema models. @@ -320,7 +317,6 @@ - @@ -346,7 +342,6 @@ - @@ -362,7 +357,7 @@ - + A field with assigned datatype 'markup-multiline' may be designated for representation with or without a containing (wrapper) element in XML. @@ -476,7 +471,7 @@ - + A field with assigned datatype 'markup-multiline' may be designated for representation with or without a containing (wrapper) element in XML. @@ -487,11 +482,16 @@ - + Any paragraph or block contents of a markup-multiline field will be represented with a containing (wrapper) element in the XML. + + + (deprecated)Alias for WRAPPED. + + With in-xml='UNWRAPPED', a field contents will be represented in the XML with no wrapper, so the field will be implicit. Among sibling fields in a given model, only one of them may be designated as UNWRAPPED. diff --git a/test-suite/README.md b/test-suite/README.md index c381f8659..3d296767f 100644 --- a/test-suite/README.md +++ b/test-suite/README.md @@ -26,5 +26,5 @@ The *beginnings* of XSpec-based unit testing of metaschema ### `oscal` -Copies of OSCAL metaschemas for testing (not normative). +Copies of OSCAL Metaschema modules for testing (not normative). diff --git a/test-suite/metaschema-xspec/markdown-types/readme.md b/test-suite/metaschema-xspec/markdown-types/readme.md index d1b9a4923..6cf850627 100644 --- a/test-suite/metaschema-xspec/markdown-types/readme.md +++ b/test-suite/metaschema-xspec/markdown-types/readme.md @@ -1,6 +1,6 @@ # Metaschema processing XSpec testing - Markdown to Markup conversion and back -Unit testing for Markdown processors supporting OSCAL Markdown. +Unit testing for Markdown processors supporting Metaschema Markdown. By defining edge cases, this aims to show a deterministic bidirectional mapping, or failing that a demonstration of where issues remain in defining or implementing such a mapping. diff --git a/toolchains/xslt-M4/schema-gen/make-metaschema-xsd.xsl b/toolchains/xslt-M4/schema-gen/make-metaschema-xsd.xsl index d62a1e9e9..f6a6ea5a1 100644 --- a/toolchains/xslt-M4/schema-gen/make-metaschema-xsd.xsl +++ b/toolchains/xslt-M4/schema-gen/make-metaschema-xsd.xsl @@ -311,7 +311,7 @@ - + diff --git a/website/.browserslistrc b/website/.browserslistrc new file mode 100644 index 000000000..5a9b70c4a --- /dev/null +++ b/website/.browserslistrc @@ -0,0 +1,5 @@ +# Supported browsers +> 2% +last 2 versions +IE 11 +not dead diff --git a/website/.htmltest.yml b/website/.htmltest.yml new file mode 100644 index 000000000..311a41b0f --- /dev/null +++ b/website/.htmltest.yml @@ -0,0 +1,7 @@ +DirectoryPath: public +CheckDoctype: false +CheckMailto: false +IgnoreExternalBrokenLinks: true +IgnoreAltMissing: true +IgnoreURLs: +IgnoreDirs: diff --git a/website/assets/scss/full-width.scss b/website/assets/scss/full-width.scss deleted file mode 100644 index ed6609a35..000000000 --- a/website/assets/scss/full-width.scss +++ /dev/null @@ -1,18 +0,0 @@ - -.grid-container { - max-width: 100%; -} - -.usa-prose > p { - max-width: 100%; -} - -.usa-section { - padding-top: 2rem; - padding-bottom: 2rem; -} - - -.usa-list li, .usa-prose > ul li, .usa-prose > ol li { - max-width: inherit; -} diff --git a/website/assets/scss/header.scss b/website/assets/scss/header.scss deleted file mode 100644 index fbe7be25b..000000000 --- a/website/assets/scss/header.scss +++ /dev/null @@ -1,38 +0,0 @@ - -.usa-header--extended { - @media all and (min-width:64em) { - .usa-logo { - max-width: 70%; - } - .usa-navbar { - max-width: 100%; - } - .usa-nav__inner { - max-width: 100%; - } - .usa-menu-btn-container { - display: none; - } - } -} - -.usa-header--basic { - @media all and (min-width:64em) { - .usa-nav-container { - max-width: 100%; - } - .usa-nav__inner { - max-width: 100%; - width: 100%; - } - .usa-nav__primary { - float: left; - } - .usa-navbar { - width: 20%; - } - .usa-nav { - padding: 0 0 .25rem 0; - } - } -} diff --git a/website/assets/scss/uswds-custom.scss b/website/assets/scss/uswds-custom.scss deleted file mode 100644 index e24cb669c..000000000 --- a/website/assets/scss/uswds-custom.scss +++ /dev/null @@ -1,12 +0,0 @@ -//@import 'uswds'; -@import 'header'; -@import 'full-width'; - -.nist-footer { - font-family: inherit; -} -/* -aside.toc { - float: right; -} -*/ diff --git a/website/config.yaml b/website/config.yaml index 7840d32db..df6c77177 100644 --- a/website/config.yaml +++ b/website/config.yaml @@ -4,13 +4,16 @@ relativeURLs: true canonifyURLs: true defaultContentLanguage: en disableAliases: false +languageCode: "en-us" languages: en: lang: en languageName: English weight: 1 MetaDataFormat: "yaml" -theme: "uswds" +theme: +- "uswds-nist" +- "uswds" googleAnalytics: UA-66610693-1 enableGitInfo: true enableRobotsTXT: true @@ -31,9 +34,9 @@ params: header: project_shortname: "Metaschema" project_name: "Metaschema Information Modeling Framework" - custom_css: contentRepoPath: https://github.com/usnistgov/metaschema/tree/master/docs/content searchAffiliate: oscal + usabanner: true menu: secondary: - name: Get involved diff --git a/website/content/_index.md b/website/content/_index.md index 6e6ed0c07..645d6702c 100644 --- a/website/content/_index.md +++ b/website/content/_index.md @@ -1,13 +1,19 @@ --- title: "Metaschema Information Modeling Framework" +cascade: + suppresstopiclist: true + toc: + display: true + sidenav: + collapsedepth: 4 --- -{{% usa-hero image="automation-hero.png" calloutText="Efficient" calloutAltText="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: @@ -34,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/contribute/_index.md b/website/content/contribute/_index.md index 5b9e2820d..5b5d39418 100644 --- a/website/content/contribute/_index.md +++ b/website/content/contribute/_index.md @@ -1,6 +1,5 @@ --- title: "Contribute" -heading: Welcome to the Metaschema Community date: 2019-09-23T19:14:12-04:00 aliases: - /community/ @@ -10,9 +9,11 @@ menu: weight: 50 --- -We are excited that you want to contribute to the Metaschema project. We are striving to provide a collaborative environment for professionals to contribute to the project's goals and objectives. +# Welcome to the Metaschema Community -# Contributing +We are excited that you want to contribute to the Metaschema project. We are striving to provide a collaborative environment for professionals and hobbyists alike to contribute to the project's goals and objectives. + +## Contributing We use GitHub as a collaboration platform for the development of the Metaschema framework. Within the project's GitHub repository you will find: diff --git a/website/content/contribute/contact.md b/website/content/contribute/contact.md index f3c493053..795517a63 100644 --- a/website/content/contribute/contact.md +++ b/website/content/contribute/contact.md @@ -3,9 +3,9 @@ title: Contact Us description: Contact Us --- -This project has been split from the [Open Security Controls Assessment Language](https://pages.nist.gov/OSCAL) project from which it originated. As a result, we are still using some of the OSCAL contact information. +# Contact Us -Please email the [OSCAL team](mailto:oscal@nist.gov) with any questions you have about this project or if you are interested in getting involved. +Please email the [project team](mailto:metaschema@nist.gov) with any questions you have about this project or if you are interested in getting involved. Please visit our [GitHub repository](https://github.com/usnistgov/metaschema) for more information, schemas, and examples. diff --git a/website/content/specification/_index.md b/website/content/specification/_index.md index 471cfeab0..0e876c8b0 100644 --- a/website/content/specification/_index.md +++ b/website/content/specification/_index.md @@ -1,50 +1,30 @@ --- -title: "Specification" -Description: "Metaschema specification" -heading: Introduction +title: "Metaschema Specification" +description: "Metaschema specification" menu: primary: name: Specification weight: 10 +aliases: +- /specification/concepts/ +- /specification/concepts/architecture-mermaid/ --- -The primary use of a metaschema is to generate format specific schema definitions for a given serializable form (e.g., XML, JSON, YAML). These generated schema can be used to validate that data is conformant to the asscoiated format, and thus conformant to the model defined by the Metaschema. +# Metaschema Specification -A Metaschema can be used to automatically generate converters capable of converting content that is schema conformant to one Metaschema generated format to another format generated by the same Metaschema. This is possible because the Metaschema allows data in one format to be mapped to the defined information model, and from the information model to the other format. In this way the Metaschema provides a *supermodel*, or [information model](concepts/terminology/#information-model), that unifies each related format. +The Metaschema Information Modeling Framework provides a standardized, format-agnostic information modeling approach supporting schema, code, and documentation generation *all in one*. -Additionally, a Metaschema can be used to automatically generate format specific model documentation that is aligned with the concepts used in a given format. +This specification defines the core concepts, syntax and semantics of the Metaschema Information Modeling Framework. -Finally, a Metaschema can be used to automatically generate language-specific data structures or classes, and serializers/deserializers that are capable of writing and reading data that is conformant in a given Metaschema derived format using the language-specific data structures. This generative approach allows application developers to focus right away on business logic and user interface features instead of building the basic common data structures needed for all applications that work with information from a given domain. +The specification is divided into the following sections. -These Metaschema capabilities, which can be applied to any information domain, serve the needs of developers who need to support multiple data formats for a given domain, or that need to choose a specific technology stack that is well-suited to their application. In either case, use of the generative capabilities of the Metaschema allow content to be easily converted to a given format, and for modeling efforts to be multipled across a number of formats without incuring additional overhead for the additional formats. +- [**Overview:**](overview/) Provides a high-level description of the framework's design goals and overall approach to defining an [information model](/specification/glossary/#information-model). +- [**Information Modeling:**](information-modeling/) Describes the information modeling approach used in the framework, with a focus on the core graph and object-oriented concepts supported by the framework. +- [**Syntax**:](syntax/) Documents the model used to describe a [Metaschema module](/specification/glossary/#metaschema-module). +- [**Data Types:**](datatypes/) Lists the built-in data types provided by the framework. +- [**Glossary**:](glossary/) Provides definitions for commonly used technical terms used in this documentation. -We hope and expect that developers' experience with different approaches will inform further efforts to unify and consolidate a coherent Metaschema-based information modeling framework. +## Conventions Used in this Document -This specification provides a basis for the development of interoperable toolchains supporting the generative capabilities of the Metaschema framework, and as a reference for information modelers producing Metaschema-based information models. +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) [RFC2119](https://www.rfc-editor.org/rfc/rfc2119.html) [RFC8174](https://www.rfc-editor.org/rfc/rfc8174.html) when, and only when, they appear in all capitals, as shown here. -## Design Goals - -The design of the Metaschema modeling approach addresses the following needs: - -1. Unify support for compatible data descriptions in multiple disparate formats, such as XML, JSON, YAML and potentially others -2. Produce schema documentation from the same source as schema files and tools -3. Enable distributed, semi-coordinated experimentation with the format(s) and related tools as supported by a given Metaschema model - -The *primary* goal is to reduce the overhead for maintaining multiple format(s) and data descriptions for a given model. This addressed in the Metaschema modeling approach providing a mechanism for all modeling to occur at the information model level. Comodity tooling can be used to produce schemas in a given format, saving time and maintenance costs. - -A *secondary* goal is to reduce the adoption costs of adopting a given model, supporting a robust community of use for content created in related data formats. This is accomplished through comodity tooling that provides content conversion utilities and programing language APIs that ease the burden of implementation for a given Metaschema-based model. - -## Design Approach - -The Metaschema provides a reduced, lightweight modeling language with certain specially-enforced constraints. The following philosophy was used in the current design: -- Use schema constructs that map cleanly into features offered by XML and JSON schema technologies . This ensures that all information can be preserved in (lossless bidirectional) conversion. -- Mediate between the structural differences in the XML, JSON, and YAML data formats by providing format-specific tailoring capabilties to improve the expression and conciseness of Metaschema-based data in a given format. -- Beyond the applicable metaschema, no further inputs and or reliance on arbitrary conventions or runtime settings should be necessary to reliably produce correspondent JSON or YAML from any metaschema-described, schema-valid XML, and vice-versa. -- Focus on the production of specifications and running code supporting automated generation of schemas and model-related artifacts, consistent with the model defined (and documented) by a given Metaschema definition. -- Test all implementations against the semantics of metaschema elements and constructs by means of continual use of unit tests. - -Since the Metaschema is designed to support only a "greatest common factor" of schema features, the supported features are a reduced from those available in a given schema language. This has the added benefit of making Metaschema easier to learn and use. - -A [metaschema definition](concepts/terminology/#metaschema-definition) describes a data structure comprising [assemblies](concepts/terminology/#assembly), each of which is composed of (more) assemblies and [fields](concepts/terminology/#field). Fields present data content while assemblies organize things. Both fields and assemblies can have [flags](concepts/terminology/#flag), which are name-value pairs further qualifying their fields or assemblies with idenifying or characterizing data. - -Comprehensive mappings from assembly, field and flag definitions, into analogous (representative) XSD and/or JSON Schema structures, enables modeling data in a neutral form. Since these mappings are fully defined, the mappings between corresponding XML and JSON expressions come for free. \ No newline at end of file diff --git a/website/content/specification/computer-example.xml b/website/content/specification/computer-example.xml new file mode 100644 index 000000000..460bf77af --- /dev/null +++ b/website/content/specification/computer-example.xml @@ -0,0 +1,171 @@ + + + Computer Model + 0.0.5 + computer + http://example.com/ns/computer + http://example.com/ns/computer + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Product Name + The product name from the vendor of the computer part. + + + Computer Assembly + A container object for a computer, its parts, and its sub-parts. + computer + + Computer Identifier + An identifier for classifying a unique make and model of computer. + + + + Build Date and Time + The date and time the computer build was completed. + + + Motherboard Assembly + A container object for a motherboard in a computer and its sub-parts. + + + + Motherboard Type + The type motherboard layout, at, atx, mini-itx or an alternative. + type + + + Motherboard Central Processing Unit (CPU) + The model number of the CPU on the motherboard of a computer. + + + + + + CPU Architecture + The Instruction Set Architecture (ISA) of the processor, x86, x86-64, arm, or an alternative. + + + CPU Speed + The clock speed of the CPU in megahertz or gigahertz. + + + + + + Motherboard Advanced Technology Attachment (ATA) Socket + The model number of ATA socket on the motherboard of a computer. There will only be one socket on any motherboard. + + + + + + ATA Socket Type + The type of ATA socket on the motherboard , pata (parallel ATA), sata (Serial ATA), or an alternative. + type + + + + + + Motherboard Random Access Memory (RAM) Module(s) + Random access memory hardware installed on the motherboard of a computer. + + + + + + + Memory Module Size + Size of the memory module in binary, not SI base-10 units, meaning a kilobyte is 1024 bytes, not 1000 bytes. + + + + + + Motherboard Expansion Card + The model number of an expansion card connected to the motherboard of a computer. + + + + + + + Expansion Card Type + The type of expansion card on a motherboard of a computer, such as pci (PCI, e.g. Peripheral Component Interconnect), pcie (PCI Express), or an alternative. + + + Peripheral Component Interconnect + Peripheral Component Interconnect Express + + + + + + + + + + Universal Serial Bus Device + A USB expansion device. + + + + USB Device Universally Unique Identifier + An identifier, based on a type 4 UUID, for the USB device. + + + + + + + + + + + + + Unique USB Device UUID + Ensures that each USB device has a unique UUID. + + + + + + Part Cost + The price paid in the specified currency. + price + + Currency Type + The type of currency. + + + + Remarks + Additional remarks related to the containing computer component. + + + + + + diff --git a/website/content/specification/concepts/_index.md b/website/content/specification/concepts/_index.md deleted file mode 100644 index 1177e737d..000000000 --- a/website/content/specification/concepts/_index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Metaschema Concepts" -Description: "Discussion of the core Metaschema concepts" -weight: 10 ---- - -An instance of a Metaschema, called a [*metaschema definition*](terminology/#metaschema-definition), defines an [*information model*](terminology/#information-model) for an aspect of given [*domain*](terminology/#domain) in a format-neutral form. A metaschema definition contains a collection of definitions for [*managed objects*](terminology/#managed-object) consisting of semantically well-defined data structures. Metaschema definitions contain documentation about the meaning (semantics) and use of a given managed object. - -A metaschema can be used to generate a schema for a corresponding [*data model*](terminology/#data-model), which is a representation of an *information model* in a format-specific serializable form (e.g., XML, JSON, YAML) expressed as an XML or JSON Schema. These generated schemas can be used to confirm (*validate*) that data to be processed by the system is encoded recognizably (consistent with the format defined by the respective schema), and thus represents information consistent with the information model defined by the Metaschema. - -Metaschemas are used to generate other model-related artifacts based on the metaschema description. These artifacts include: - -- Conversion utilities that can convert content instances between the XML and JSON formats derived from a given metaschema defintion, ensuring the resulting content is schema-valid and model-identical to its input (the conversion is lossless); -- XML and JSON model documentation for use on a website (i.e. the [OSCAL website](https://pages.nist.gov/OSCAL/documentation/schema/). -- Programing language APIs used for parsing data conformat to a given data model into a set of language-specific objects, and also writing data in language-specific objects out to one of the supported data model formats. - -Use of metaschema definitions provides a sustainable means to maintain seamless and consistent support for multiple models and multiple associated formats for each model, avoiding the need to maintain each format individually. Content can also be kept up-to-date in multiple formats using generated content converters, and can be validated using generated schemas, ensuring consistency of data models across disparate systems. Adding support for new formats (e.g., YAML) can accomplished by extending the Metaschema tooling to produce schema and converters for other formats. - -## Metaschema Architecture - -The following illustrates the Metaschema architecture: - -{{}} -graph TB - ms1[metaschema moduleA] -- include --> ms - ms2[metaschema moduleB] -- include --> ms - xmp1[example1] -- cite --> ms - xmp2[example2] -- cite --> ms - ms[main Metaschema] -- compile metaschema --> cms - cms -- extract documentation --> xmldocsh[XML docs / HTML] - cms((Compiled metaschema)) -- translate --> sch(XML Schema) - cms -- xdm::object map --> xj{xml to json XSLT} - cms -- object::xdm map --> jx{json to xml XSLT} - cms -- translate --> jsch(JSON Schema) - cms -- extract documentation --> jsondocsh[JSON docs / HTML] - -classDef metasch fill:skyblue,stroke:blue,stroke-width:12px,stroke-opacity:0.2 -classDef xml fill:gold,stroke:#333,stroke-width:2px; -classDef json fill:pink,stroke:#333,stroke-width:2px -classDef html fill:lightgreen,stroke-width:2px -classDef md fill:lightgreen,stroke-width:4px,stroke-dasharray:2,2 - -class cms,ms,ms1,ms2,xmp1,xmp2 metasch -class sch,xj xml -class jsch,jx json -class xmldocsh,jsondocsh html -class xmldocmd,jsondocmd md -{{}} - -The diagram above was [generated](architecture-mermaid) using [Mermaid](https://mermaidjs.github.io/). - diff --git a/website/content/specification/concepts/architecture-mermaid.md b/website/content/specification/concepts/architecture-mermaid.md deleted file mode 100644 index 00c1aaf53..000000000 --- a/website/content/specification/concepts/architecture-mermaid.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "Metaschema Architecture using Mermaid" -Description: "Source for the Metaschema Architecture diagram." -sidenav: - activerenderdepth: 0 ---- - -[Mermaid](https://mermaidjs.github.io/) is a notation for producing graphics from abstract node/network descriptions - - -The following is the Mermaid notation for the chart above: - -```mermaid -graph TB - ms1[module] -- include --> ms - ms2[module] -- include --> ms - xmp1[example] -- cite --> ms - xmp2[example] -- cite --> ms - ms[main Metaschema] -- compile metaschema --> cms - cms -- extract documentation --> xmldocsh[XML docs / HTML] - cms((Compiled metaschema)) -- translate --> sch(XML Schema) - cms -- xdm::object map --> xj{xml to json XSLT} - cms -- object::xdm map --> jx{json to xml XSLT} - cms -- translate --> jsch(JSON Schema) - cms -- extract documentation --> jsondocsh[JSON docs / HTML] - -classDef metasch fill:skyblue,stroke:blue,stroke-width:12px,stroke-opacity:0.2 -classDef xml fill:gold,stroke:#333,stroke-width:2px; -classDef json fill:pink,stroke:#333,stroke-width:2px -classDef html fill:lightgreen,stroke-width:2px -classDef md fill:lightgreen,stroke-width:4px,stroke-dasharray:2,2 - -class cms,ms,ms1,ms2,xmp1,xmp2 metasch -class sch,xj xml -class jsch,jx json -class xmldocsh,jsondocsh html -class xmldocmd,jsondocmd md -``` \ No newline at end of file diff --git a/website/content/specification/concepts/terminology.md b/website/content/specification/concepts/terminology.md deleted file mode 100644 index d41f94bc1..000000000 --- a/website/content/specification/concepts/terminology.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Metaschema Terminology" -Description: "Definitions of Metaschema Terms" ---- - -The following terminology is used in this specification: - -## Assembly - -An *assembly* is defined as follows: - -{{}}The [*information structure*](#information-structure) used to represent a [*managed object*](#managed-object) within a given [*metaschema definition*](#metaschema-definition).{{}} - -An assembly does not have an associated value. - -An assembly may reference or directly define zero or more [*flags*](#flag). - -An Assembly has a model consisting of references to zero or more [*assemblies*](#assembly) or [*flags*](#flag). - -## Data Model - -A *data model*, abbreviated as DM, is defined as follows: - -{{}}A representation of an [*information model*](#information-model) in a format specific serializable form (e.g., XML, JSON, YAML) expressed in a format-specific schema definition syntax. The format-specific schema definition is generated within the Metaschema architecture from the [*metaschema-definition*](#metaschema-definition). These generated schema can be used to validate that data is conformant to the asscoiated format, and thus conformant to the *information model* defined by a given *metaschema defintion*.{{}} - -> As described by [RFC 3444](https://tools.ietf.org/html/rfc3444#section-4)), a data model is defined at a lower level of abstraction and include many details. - -> - Intended for implementors -> - Include protocol-specific constructs. - -## Domain - -An *domain* is defined as follows: - -{{}}A specific area of knowledge, interest, and/or practice.{{}} - -## Flag - -A *flag* is defined as follows: - -{{}}A simple named data element with an associated scalar value. A *flag* is a simple [*information structure*](#information-structure) used to represent a part of a [*managed object*](#managed-object) within a given [*metaschema definition*](#metaschema-definition).{{}} - -A *flag* is a pairing of a name and a value. - -A flag typically provides identifying or classifying information for the containing assembly or field. - -## Field - -A *field* is defined as follows: - -{{}}A complex named data element with an associated scalar or markup typed value and zero or more flags. A *field* is a complex [*information structure*](#information-structure) used to represent a part of a [*managed object*](#managed-object) within a given [*metaschema definition*](#metaschema-definition).{{}} - -A field has a required value. - -A field may reference or directly define zero or more [*flags*](#flag). - -A field does not have a model. - -A field provides supporting information for the containing assembly. - -## Information Model - -An *information model*, abbreviated as IM, is defined as follows: - -{{}}A format-neutral description of a set of [*managed objects*](#managed-object) for a given [*domain*](#domain).{{}} - -> As described by [RFC 3444](https://tools.ietf.org/html/rfc3444#section-3)), an IM describes managed objects at a conceptual level, independent of any specific implementations or protocols used to transport the data. - -> - Level of abstraction depends on the modeling needs of the designers -> - Define relationships between managed objects -> - Should hide all protocol or implementation details, allowing for different implementations - -## Information Structure - -An *information structure* is defined as follows: - -{{}}A description of heirarchically related information elements, along with their cardinalities, representing a semanticly well-defined data structure.{{}} - -## Managed Object - -An *managed object* is defined as follows: - -{{}}A given concept within a specific [*domain*](#domain) consisting of a defined [*information structure*](#information-structure).{{}} - -A *managed object* is represented by an [*assembly*] in a [*metaschema definition*](#metaschema-definition). - -## Metaschema Definition - -An *metaschema definition* is defined as follows: - -{{}}A format for describing the [*managed objects*](#managed-object) in an [*information model*](#information-model) using Metaschema syntax. For each managed object, details are provided about its structure, meaning (semantics) and use.{{}} - -A metaschema definition consists of a few different types of information elements: - -- **Flag:** A named data element with an associated scalar value. A simple name / value pair. -- **Field:** A complex named data element with an associated scalar or markup typed value and zero or more flags. -- **Assembly:** A complex named data object, with no value, zero or more flags, and a complex model consisting of a combination of child fields and assemblies. - -![A metaschema definition is composed of flag, field, and assembly definitions. A flag has a value. A Field has a value and may associate zero or more flags. An assembly has no value, may associate zero or more flags, and has a model which may associate zero or more assemblies or fields.](../metaschema-information-elements.png) - -*Flags* and *fields* are leaf information elements that support the managed object. - -A metaschema definition is used as the basis for producing schema files, conversion files, documentation and utilities in support of that format. For any given model defined by a metaschema, the XML Schema (XSD) and JSON Schema will be consistent to a common information model because they are produced from the same metaschema definition. diff --git a/website/content/specification/syntax/datatypes.md b/website/content/specification/datatypes.md similarity index 59% rename from website/content/specification/syntax/datatypes.md rename to website/content/specification/datatypes.md index c4f2ff33c..0c5ec833c 100644 --- a/website/content/specification/syntax/datatypes.md +++ b/website/content/specification/datatypes.md @@ -1,157 +1,94 @@ --- -title: Metaschema Data Types -heading: Data Types Used in Metaschema -description: A description of the data types used in Metaschema-based models. -weight: 10 -suppressintopiclist: true -sidenav: - title: Data Types -toc: - enabled: true +title: "Metaschema Data Types" +linkTitle: "Data Types" +description: "A description of the built in data types supported by Metaschema." +weight: 60 --- -The Metaschema models use a set of data type primitives. These data types are documented in the following sections. +# Data Types Used in Metaschema -## Simple Data types +Metaschema is a strongly typed modeling language, that uses a collection of built in data types to represent data elements within a Metaschema-based model. -### boolean +Metaschema's data types represent a data-oriented, leaf nodes in a Metaschema-based model. These data types provide the basis for data elements that have clearly defined syntax and semantics. -A boolean value mapped in XML, JSON, and YAML as follows: -| Value | XML | JSON | YAML | -|:--- |:--- |:--- |:--- | -| true | `true` or `1` | `true` | `true` | -| false | `false` or `0` | `false` | `false` | +There are 2 kinds of data types. -In XML Schema this is represented as a restriction on the built-in type [boolean](https://www.w3.org/TR/xmlschema11-2/#boolean) as follows: +- **[simple data types:](#simple-data-types)** that represent basic data value primitives with a specific syntax and semantics. +- **[markup data types:](#markup-data-types)** that represent semantically formatted text that is intended for presentation. -```XML - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` +A data type can be referenced in a metaschema definition within a `define-field`, `field`, `define-flag`, or `flag` component definition using the `@as-type` attribute. The following are the allowed data types. -In JSON Schema, this is represented as: +## Data Type Schema Representations -```JSON -{ - "type": "boolean" -} -``` +JSON and XML Schema instances are provided for the built in data types. -### decimal +### JSON Schema -A real number expressed using decimal numerals. +A single JSON schema is [provided](https://github.com/usnistgov/metaschema/blob/develop/schema/json/metaschema-datatypes.json) for all built in data types supporting JSON and YAML validation. This schema is based on JSON Schema draft-07 ([JSON Schema](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-01) and [JSON Schema Validation 01](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-validation-01)). -In XML Schema this is represented as a restriction on the built-in type [decimal](https://www.w3.org/TR/xmlschema11-2/#decimal) as follows: +The data type JSON schema uses regular expression patterns to enforce the syntax of specific data types. The regular expressions supported in JSON schema using the [`pattern`](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-validation-01#section-6.3.3) keyword are based on the [ECMA 262 regular expression dialect](https://262.ecma-international.org/#sec-regexp-regular-expression-objects). -```XML - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` +### XML Schemas -In JSON Schema, this is represented as: +Multiple XML Schemas are provided that support different groups of data types. -```JSON -{ - "type": "number", - "pattern": "(\\+|-)?([0-9]+(\\.[0-9]*)?|\\.[0-9]+)" -} -``` +The [Simple data types](#simple-data-types) are defined in [a single XML Schema](https://github.com/usnistgov/metaschema/blob/develop/schema/xml/metaschema-datatypes.xsd). -### empty +The [markup data types](#markup-data-types) are supported by multiple schemas. -This data type indicates that the model information element contains no value content, but may contain other structured information elements. +The [`markup-line`](#markup-line) data type is implemented in XML Schema within the [metaschema-markup-line.xsd](https://github.com/usnistgov/metaschema/blob/develop/schema/xml/metaschema-markup-line.xsd) schema. -In XML, this may represent an element without text content. +The [`markup-multiline`](#markup-multiline) data type is implemented in XML Schema within the [metaschema-markup-multiline.xsd](https://github.com/usnistgov/metaschema/blob/develop/schema/xml/metaschema-markup-multiline.xsd) schema. -In JSON, this may represent an object with labels corresponding to other child information elements, but no label corresponding to a text value. +Both of these schemas use a set of shared XML Schema types from the [metaschema-prose-base.xsd](https://github.com/usnistgov/metaschema/blob/develop/schema/xml/metaschema-prose-base.xsd). -**Note: Use of this data type has been *deprecated* with no replacement, since this can be handled with format-specific syntax.** +The [metaschema-prose-module.xsd](https://github.com/usnistgov/metaschema/blob/develop/schema/xml/metaschema-prose-module.xsd) XML schema is provided as a convenience to support use of both the `markup-line` and `markup-multiline` data types. -### integer +XML Schema uses its [own dialect](https://www.w3.org/TR/xmlschema-2/#regexs) of regular expressions. -An integer value. +### Regular Expressions in Schemas -In XML Schema this is represented as a restriction on the built-in type [integer](https://www.w3.org/TR/xmlschema11-2/#integer) as follows: +Regular expressions used in JSON and XML Schemas use a reduced subset of regular expression syntax that is intended to be well supported by most regular expression dialects. -```XML - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` +Regular expression features used include: -In JSON Schema, this is represented as: +- Single line matching +- Unicode characters +- Grouping +- Character classes, including use of Unicode property value expressions (e.g., `\p{L}`, `\p{N}`) +- Class ranges +- Class negation +- Quantifiers -```JSON -{ - "type": "integer" -} -``` +These features tend to be widely supported by implementations based on the [Perl Compatible Regular Expression (PCRE)](https://www.pcre.org/), [ECMA](https://262.ecma-international.org/#sec-regexp-regular-expression-objects), [Java](https://cr.openjdk.org/~iris/se/19/latestSpec/api/java.base/java/util/regex/Pattern.html), and [XML Schema 1.0](https://www.w3.org/TR/xmlschema-2/#regexs) regex dialects. As a result, implementations based on any of these standards should be able to support the patterns used in the Metaschema JSON and XML data type schemas. -### nonNegativeInteger +## Simple Data Types -An integer value that is equal to or greater than `0`. +These data types represent the basic data primitives used in Metaschema to support different types of data values. -In XML Schema this is represented as a restriction on the built-in type [nonNegativeInteger](https://www.w3.org/TR/xmlschema11-2/#nonNegativeInteger) as follows: +- **numeric values:** [decimal](#decimal), [integer](#integer), [non-negative-integer](#non-negative-integer), [positive-integer](#positive-integer) +- **temporal values:** [date](#date), [date-with-timezone](#date-with-timezone), [date-time](#date-time), [date-time-with-timezone](#date-time-with-timezone), [day-time-duration](#day-time-duration), [year-month-duration](#year-month-duration) +- **binary values:** [base64](#base64), [boolean](#boolean) +- **character-based values:** [email-address](#email-address), [hostname](#hostname), [ip-v4-address](#ip-v4-address), [ip-v6-address](#ip-v6-address), [string](#string), [token](#token), [uri](#uri), [uri-reference](#uri-reference), [uuid](#uuid) -```XML - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` +Details of these data types follow. -In JSON Schema, this is represented as: +### base64 -```JSON -{ - "type": "integer", - "minimum": 0 -} -``` +A string representing arbitrary binary data encoded using the [Base 64 algorithm](https://www.rfc-editor.org/rfc/rfc4648#section-4) as defined by [RFC4648](https://www.rfc-editor.org/rfc/rfc4648). -### positiveInteger +In XML Schema this is represented as a restriction of the built-in type [base64Binary](https://www.w3.org/TR/xmlschema11-2/#base64Binary) that doesn't allow leading and trailing whitespace. -A positive integer value. - -In XML Schema this is represented as a restriction on the built-in type [positiveInteger](https://www.w3.org/TR/xmlschema11-2/#nonNegativeInteger) as follows: +This data type is defined in XML as follows: ```XML - - - + + + - A trimmed string, at least one character with no leading or - trailing whitespace. + A trimmed string, at least one character with no + leading or trailing whitespace. @@ -162,56 +99,62 @@ In JSON Schema, this is represented as: ```JSON { - "type": "integer", - "minimum": 1 + "type": "string", + "pattern": "^[0-9A-Za-z+/]+={0,2}$", + "contentEncoding": "base64" } ``` -## Formatted String Data types - -The following are data types based on strings. +### boolean -### base64Binary +A boolean value mapped in XML, JSON, and YAML as follows: -A string representing arbitrary Base64-encoded binary data. +| Value | XML | JSON | YAML | +|:--- |:--- |:--- |:--- | +| true | `true` or `1` | `true` | `true` | +| false | `false` or `0` | `false` | `false` | -In XML Schema this is represented as a restriction on the built-in type [base64Binary](https://www.w3.org/TR/xmlschema11-2/#base64Binary) as follows: +In XML Schema this is represented as a restriction on the built-in type [boolean](https://www.w3.org/TR/xmlschema11-2/#boolean) as follows: ```XML - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - + + + ``` +The pattern `true|false|0|1` above ensures that leading and trailing whitespace is not allowed in XML-based Metaschema instances using this data type. + In JSON Schema, this is represented as: ```JSON { - "type": "string", - "pattern": "^[0-9A-Fa-f]+$", - "contentEncoding": "base64" + "type": "boolean" } ``` ### date -This is the same as [date-with-timezone](#date-with-timezone), except the time zone portion is optional. +A string representing a 24-hour period, optionally qualified by a timezone. A `date-with-timezone` is formatted according to "full-date" as defined [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.6), with the addition of an optional timezone, specified as a time-offset according to RFC3339. + +This is the same as [date-with-timezone](#date-with-timezone), except the timezone portion is optional. This can be used to support formats that have ambiguous timezones for date values. + +For example: + +``` +2019-09-28Z +2019-09-28 +2019-12-02-08:00 +2019-12-02 +``` In XML Schema this is represented as a restriction on the built-in type [date](https://www.w3.org/TR/xmlschema11-2/#date) as follows: ```XML - + ``` @@ -227,7 +170,9 @@ In JSON Schema, this is represented as: ### date-with-timezone -A string representing a 24-hour period in a given timezone. A `date-with-timezone` is formatted according to "full-date" as defined [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.6). This type additionally requires that the time-offset (timezone) is always provided. +A string representing a 24-hour period in a given timezone. A `date-with-timezone` is formatted according to "full-date" as defined [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.6), with the addition of a timezone, specified as a time-offset according to RFC3339. + +This type requires that the time-offset (timezone) is always provided. This use of timezone ensure that date information exchanged across timezones is unambiguous. For example: @@ -241,9 +186,7 @@ In XML Schema this is represented as a restriction on the built-in type [date](h ```XML - + ``` @@ -257,18 +200,30 @@ In JSON Schema, this is represented as: } ``` -### dateTime +### date-time -This is the same as [dateTime-with-timezone](#datetime-with-timezone), except the time zone portion is optional. +A string representing a point in time, optionally qualified by a timezone. This date and time value is formatted according to "date-time" as defined [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.6), except the timezone (time-offset) is optional. + +This is the same as [date-time-with-timezone](#date-time-with-timezone), except the timezone portion is optional. This can be used to support formats that have ambiguous timezones for date/time values. + + +For example: + +``` +2019-09-28T23:20:50.52Z +2019-09-28T23:20:50.52 +2019-12-02T16:39:57-08:00 +2019-12-02T16:39:57 +2019-12-31T23:59:60Z +2019-12-31T23:59:60 +``` In XML Schema this is represented as a restriction on the built-in type [dateTime](https://www.w3.org/TR/xmlschema11-2/#dateTime) as follows: ```XML - + ``` @@ -282,9 +237,11 @@ In JSON Schema, this is represented as: } ``` -### dateTime-with-timezone +### date-time-with-timezone -A string containing a date and time formatted according to "date-time" as defined [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.6). This type requires that the time-offset (timezone) is always provided. This use of timezone ensure that date/time information that is exchanged across timezones is unambiguous. +A string representing a point in time in a given timezone. This date and time value is formatted according to "date-time" as defined [RFC3339](https://tools.ietf.org/html/rfc3339#section-5.6). + +This type requires that the time-offset (timezone) is always provided. This use of timezone ensures that date/time information exchanged across timezones is unambiguous. For example: @@ -299,9 +256,7 @@ In XML Schema this is represented as a restriction on the built in type [dateTim ```XML - + ``` @@ -316,9 +271,69 @@ In JSON Schema, this is represented as: } ``` -### email +### day-time-duration + +An amount of time quantified in days, hours, minutes, and seconds based on [ISO-8601 durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) (see also [RFC3339 appendix A](https://www.rfc-editor.org/rfc/rfc3339.html#appendix-A)). + +Examples include: + +The duration of 1 day, 12 hours, and 45 minutes can be represented as: + +``` +P1DT12H45M +``` + +The using the optional minus sign, the negative duration of 3 hours can be represented as: -An email address string formatted according to [RFC 6531](https://tools.ietf.org/html/rfc6531). +``` +-PT3H +``` + +In XML Schema this is defined by [dayTimeDuration](https://www.w3.org/TR/xmlschema11-2/#dayTimeDuration), which is a restriction on the built-in type [duration](https://www.w3.org/TR/xmlschema11-2/#duration) as follows: + +```XML + + + + + +``` + +In JSON Schema, this is represented as: + +```JSON +{ + "type": "string", + "format": "duration", + "pattern": "^-?P([0-9]+D(T(([0-9]+H([0-9]+M)?(([0-9]+|[0-9]+(\\.[0-9]+)?)S)?)|([0-9]+M(([0-9]+|[0-9]+(\\.[0-9]+)?)S)?)|([0-9]+|[0-9]+(\\.[0-9]+)?)S))?)|T(([0-9]+H([0-9]+M)?(([0-9]+|[0-9]+(\\.[0-9]+)?)S)?)|([0-9]+M(([0-9]+|[0-9]+(\\.[0-9]+)?)S)?)|([0-9]+|[0-9]+(\\.[0-9]+)?)S)$" +} +``` + +### decimal + +A real number expressed using a whole and optional fractional part separated by a period. + +In XML Schema this is represented as a restriction on the built-in type [decimal](https://www.w3.org/TR/xmlschema11-2/#decimal) as follows: + +```XML + + + + + +``` + +In JSON Schema, this is represented as: + +```JSON +{ + "type": "number", + "pattern": "(\\+|-)?([0-9]+(\\.[0-9]*)?|\\.[0-9]+)" +} +``` +### email-address + +An email address string formatted according to [RFC6531](https://tools.ietf.org/html/rfc6531). In XML Schema this is represented as a restriction on the built in type [string](https://www.w3.org/TR/xmlschema11-2/#string) as follows: @@ -346,7 +361,7 @@ In JSON Schema, this is represented as: ### hostname -An internationalized Internet host name string formatted according to [section 2.3.2.3](https://tools.ietf.org/html/rfc5890#section-2.3.2.3) of RFC 5890. +An internationalized Internet host name string formatted according to [section 2.3.2.3](https://tools.ietf.org/html/rfc5890#section-2.3.2.3) of RFC5890. In XML Schema this is represented as a restriction on the built in type [string](https://www.w3.org/TR/xmlschema11-2/#string) as follows: @@ -370,18 +385,38 @@ In JSON Schema, this is represented as: Once a suitable pattern for XML is developed, this pattern will be ported to JSON for more consistent validation. +### integer + +A whole number value. + +In XML Schema this is represented as a restriction on the built-in type [integer](https://www.w3.org/TR/xmlschema11-2/#integer) as follows: + +```XML + + + + + +``` + +In JSON Schema, this is represented as: + +```JSON +{ + "type": "integer" +} +``` + ### ip-v4-address -An Internet Protocol version 4 address in dotted-quad ABNF syntax as defined in [section 3.2](https://tools.ietf.org/html/rfc2673#section-3.2) of RFC 2673. +An Internet Protocol version 4 address represented using dotted-quad syntax as defined in [section 3.2](https://tools.ietf.org/html/rfc2673#section-3.2) of RFC2673. In XML Schema this is represented as a restriction on the built in type [string](https://www.w3.org/TR/xmlschema11-2/#string) as follows: ```XML - + ``` @@ -398,7 +433,7 @@ In JSON Schema, this is represented as: ### ip-v6-address -An Internet Protocol version 6 address in dotted-quad ABNF syntax as defined in [section 2.2](https://tools.ietf.org/html/rfc3513#section-2.2) of RFC 3513. +An Internet Protocol version 6 address represented using the syntax defined in [section 2.2](https://tools.ietf.org/html/rfc3513#section-2.2) of RFC3513. In XML Schema this is represented as a restriction on the built in type [string](https://www.w3.org/TR/xmlschema11-2/#string) as follows: @@ -406,9 +441,7 @@ In XML Schema this is represented as a restriction on the built in type [string] - + ``` @@ -423,15 +456,61 @@ In JSON Schema, this is represented as: } ``` -### NCName +### non-negative-integer -A non-colonized name as defined by [XML Schema Part 2: Datatypes Second Edition](https://www.w3.org/TR/xmlschema11-2/#NCName). +An integer value that is equal to or greater than `0`. + +In XML Schema this is represented as a restriction on the built-in type [nonNegativeInteger](https://www.w3.org/TR/xmlschema11-2/#nonNegativeInteger) as follows: + +```XML + + + + + +``` + +Note: The pattern above ensures that leading and trailing whitespace is not allowed in XML-based Metaschema instances using this data type. -**Note: Use of this data type has been *deprecated* in favor of [token](#token), which has a similar syntax.** `NCName` was replaced with `token` to avoid use of an XML-specific type. This data type is no longer in use, but is still provided here to support model documentation for older Metaschema revisions that make use of this data type. +In JSON Schema, this is represented as: + +```JSON +{ + "type": "integer", + "minimum": 0 +} +``` + +### positive-integer + +An integer value that is greater than `0`. + +In XML Schema this is represented as a restriction on the built-in type [positiveInteger](https://www.w3.org/TR/xmlschema11-2/#nonNegativeInteger) as follows: + +```XML + + + + + +``` + +Note: The pattern above ensures that leading and trailing whitespace is not allowed in XML-based Metaschema instances using this data type. + +In JSON Schema, this is represented as: + +```JSON +{ + "type": "integer", + "minimum": 1 +} +``` ### string -A string of Unicode characters, but not empty and not whitespace-only (whitespace is U+9, U+10, U+32 or [ \n\t]+). +A non-empty string of unicode characters with leading and trailing whitespace disallowed. + +Whitespace is: `U+9`, `U+10`, `U+32` or `[ \n\t]+`. In XML Schema this is represented as a restriction on the built in type [string](https://www.w3.org/TR/xmlschema11-2/#string) as follows: @@ -439,16 +518,13 @@ In XML Schema this is represented as a restriction on the built in type [string] - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - + ``` +Note: The pattern above ensures that leading and trailing whitespace is not allowed in XML-based Metaschema instances using this data type. + In JSON Schema, this is represented as: ```JSON @@ -492,7 +568,7 @@ In XML Schema this is represented as a restriction on the built in type [anyURI] - Requires a scheme with colon per RFC 3986. + Requires a scheme with colon per RFC3986. @@ -511,23 +587,24 @@ In JSON Schema, this is represented as: ### uri-reference -A URI Reference (either a URI or a relative-reference) formatted according to [section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1) of RFC3986. +A URI Reference, either a URI or a relative-reference, formatted according to [section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1) of RFC3986. In XML Schema this is represented as a restriction on the built in type [anyURI](https://www.w3.org/TR/xmlschema11-2/#anyURI) as follows: ```XML + + A trimmed URI having at least one character with no + leading or trailing whitespace. + - - - A trimmed URI, at least one character with no leading or - trailing whitespace. - - + ``` +Note: The pattern above ensures that leading and trailing whitespace is not allowed in XML-based Metaschema instances using this data type. + In JSON Schema, this is represented as: ```JSON @@ -539,18 +616,18 @@ In JSON Schema, this is represented as: ### uuid -A version 4 or 5 Universally Unique Identifier (UUID) as defined by [RFC 4122](https://tools.ietf.org/html/rfc4122). +A version 4 or 5 Universally Unique Identifier (UUID) as defined by [RFC4122](https://tools.ietf.org/html/rfc4122). In XML Schema this is represented as a restriction on the built in type [string](https://www.w3.org/TR/xmlschema11-2/#string) as follows: ```XML - + - A sequence of 8-4-4-4-12 hex digits, with extra constraints in - the 13th and 17-18th places for version 4 and 5 + A sequence of 8-4-4-4-12 hex digits, with + extra constraints in the 13th and 17-18th places for version + 4 and 5. @@ -566,6 +643,45 @@ In JSON Schema, this is represented as: } ``` +### year-month-duration + +An amount of time quantified in years and months based on [ISO-8601 durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) (see also [RFC3339 appendix A](https://www.rfc-editor.org/rfc/rfc3339.html#appendix-A)). + +Examples include: + +The duration of 1 year and 6 months can be represented as: + +``` +P1Y6M +``` + +The using the optional minus sign, the negative duration of 9 months can be represented as: + +``` +-P9M +``` + +In XML Schema this is defined by [dayTimeDuration](https://www.w3.org/TR/xmlschema11-2/#dayTimeDuration), which is a restriction on the built-in type [duration](https://www.w3.org/TR/xmlschema11-2/#duration) as follows: + +```XML + + + + + +``` + +In JSON Schema, this is represented as: + +```JSON +{ + "type": "string", + "format": "duration", + "pattern": "^-?P([0-9]+Y([0-9]+M)?)|[0-9]+M$" +} +``` + + ## Markup Data Types Structured prose text is designed to map cleanly to equivalent subsets of HTML and Markdown. This allows HTML-like markup to be incorporated in Metaschema XML-based content using an element set maintained in the Metaschema namespace. This HTML-equivalent element set is not intended to be treated directly as HTML, but to be readily and transparently converted to HTML (or other presentational formats) as needed. Similarly, Metaschema uses a subset of Markdown for use in Metaschema JSON- and YAML-based content. A mapping is supported between the HTML-like element set and the Markdown syntax, which supports transparent and lossless bidirectional mapping between both markup representations. diff --git a/website/content/specification/def-inst.svg b/website/content/specification/def-inst.svg new file mode 100644 index 000000000..26623a3a9 --- /dev/null +++ b/website/content/specification/def-inst.svg @@ -0,0 +1,92 @@ + + + + + + + + + + + + + + + + Page-1 + + Rectangle.18 + Assmebly: asmb-def-1 + + Assmebly: asmb-def-1 + + Rectangle.19 + flg-inst-1 + + flg-inst-1 + + Rectangle.22 + model + + model + + Rectangle.20 + asmb-inst-1 + + asmb-inst-1 + + Rectangle.21 + fld-inst-1 + + fld-inst-1 + + Rectangle.25 + Field: fld-def-1 + + Field: fld-def-1 + + Rectangle.26 + flg-inst-2 + + flg-inst-2 + + Rectangle.30 + Flag: flg-def-1 + + Flag: flg-def-1 + + Rectangle.31 + Assembly: asmb-def-2 + + Assembly: asmb-def-2 + + Dynamic connector + + + + Dynamic connector.33 + + + + Dynamic connector.34 + + + + Dynamic connector.35 + + + + diff --git a/website/content/specification/def-inst.vsdx b/website/content/specification/def-inst.vsdx new file mode 100644 index 0000000000000000000000000000000000000000..20d9571e22d07de6ec7eac0e1c81afc024413c5d GIT binary patch literal 32341 zcmeEtW0z>LmTkG}lx^F#ZS$0E+qP}nwr$(CZJc-R?S6Ok8-4p1^xGe@KO}o6nIm&$ zWvv-`DPRy}05AXu000020B%7V%qTzr00l4r03-kiAWb1#8z*BMCtYQCJ7Y&}S~qJe z`~nal@;m^bzwQ73^S>B@rsQ#(0eWPS*W?el_*NAIJp~mMf00n*$p9Ze<6ggIw>ayP z-djhACShsRixCBbUC)}*)P1+=3#(r+pPl9$Cj8*tJ4DB#;By3U z^MO$zwes~MI1Q~VK0Bm35|Y@g;F$};}5JV z{u3rqxl)&S^dG+juQ;Ti(dI6A?K!fM<7CpH@TB!!I+ECFD4})9v)t@=$iP&1ZJC4Z ztb#KY$Vs1R*Uf=yeEOz~u9-lWBo#5fokS@O?(iTYOUDoEhggSu5VUgoYCRV|gx8H7 zx#0$?5)4`sCU*dB>E}wiN#FNnW@S_)U_T9a)`%Hu*DtWr(`*i+o__~pYt=vFY}FVE zJKM}dXvNjhVUE_E6?p7@Si~J9 zpJ)TG=n4@GhkhktfWT)YSMhRN4+%<0VmwdFgS+c#Qq!ezD?QtSUf|MlB$DD7qRLrp zt@+UU;eOwzPFx4+VOoFW8Rey|ty`^A4=x#NQ0i?YF+7ssD*U4mM$W|y&vZIpk~snj zoD`Fff_ntsM4saALpPucqZ7@%E}G13wFG1OyhC>C*c2=P1PUV9;Rl6>sE(g)qR$e9 zT7EP!o~j%Z8bht%$N}ZN_9os{eU|R?Amurw}J|_(5 z4qo`snVNF$U!eXwtGrC6y}?ib01$!!01*GSa4~l@x1}?(HFUQAyFvbAXS~wZbUbXU z_u*4{hpV^>OpuJO?!2P$RP6A`YUYVKZnx5rokz4{5Q>KsaUc1-T!evVD-clV#Jc6I zS83)l@CCq(2J4tNlPB~2Zi%pnrQQyb@Y1lwWxilRolO)$=gV4YUH{H3^ti6I{d4C_ zh9~3~mH6&5d{6~ed@yb9oo;-23kS#cNTLav8K}Z8mnh?qi!+tDtnc89H?zJ^gvxEj zl2JXV0zcxc@bbAtkzJ(@{TK0b$}v`OiH|rn0?lAa%b*f7`uVssT98Ed)Lr0n;2G|kPn=WDiQDWGP zVR(cs96_|a!+;Q9)G%m?>}`>22iA{Aac&+C*`yemkv%p$tg^7z;1NC0D^mrL;0Zn$ zR*dq&+z50Xl8p{pIEtR{Hfs^ zmc#Lw$OkK;B2fAf6YxM>*z-j$q9e%G>1DZ)hoAHApLC-)m)S%<`Yp(5_yr%wYL-=Y zT;|D*gQpNz5(M4xmXA;K>pc2SNPs`m(Is}|E+1dAV^rx&9-d@d7LN~ESfZ6@7!Fin z!CLljnl!vT)UZKJ zvZGp}my4J{vg2B`)lquduO`8!cisjX6Z!9d4-d!ZlQ0W&5^mfe9fJ~Vj#dAF**R8 zeBQ=h0#}mPkHm)FR0@nGL)YTe&?d-Hv^D_~e8uuKbKWJ9q%sQtXVf=)#T?{~QqNJ0 zI>JJ&)L9>3-X+jnsCJKNVczLCK+|C{fYUE-KUcl$QVGuAwS{Clz35L}K2{${P`C60RND&^ zx>9P@yzPAuvuV=yWF%|Q5Y8vHi!iU9&!xUEIYZ59Qtuww~wAlCGG*04!COet4 zu?Kqz-|c%B=_m9r>=*hNnWGAZf+@W5OH*Y%;}$1q2JhLVki09i!;2E-YW{Y^F4@x! z+`MrSU%tlph&1{+R%#ndu~8uIW?DgZ*=MsV?l{Nl8Cqa3{Xzg<7U12en^ghOfIYa+;r% z*FC>q&`}^Yt7JTaO=D!4<|-?l{>+I6o4&mloHVQ$S&X!nFa{7vvm(KwL_$kr+`UV0 z_w0eq3dg@w0ErLGeC+jz_MOt*_jT4)pvzB&N+h~=k$!}RQv};sK|+ByGxS&gUFb8= z(~O*$W=zCU%dgE-3d6`wy`N!{gP0thd_K_m)XSvpM&tmppg6sUt&;sg;KWK}>j@mJ zr6_CUG$t%kB^7e<6ccc0YEg4HxT%g=Hp96U^#&OV(%OW`yZB>35Q94Y)xOHFaP5XC z|Fc6CASHr!vQR`)^hh-StM2_YZ9hW~-jl3`x9QOIaoScQzPi#{i4OR$H07&_PxL^} zE!BHUYAVo218gG!-WZ>7;2C)^KAQ&!Mx0%dLUQGedf;z&k92AmMtsVZ%dr?qIsz9I zgIibCuNVdNppQzQBH&)85X?Oq9ueo_3^8Sx8RwQI|(lVRw)grh@f%L zs>#jod12Y~z;cl1F}>?MwgOB?A7;`!9DDlhN(GuJd3VJJZ-k-*tj_MEQuLbuR>(4M%hJV^27H7w@n%qlzH3Kb(`iXb1**>5%e`b?M@p zy>_*X0G=v~-181zu534#Gfesb-mv0S{0^nY*2{nZbT|z0N)*Ub8H92lA=}VNlhRLs zSv19xQp?OSF8rzbwZiGvh$6KvU^e}tg&GeQgwp_1F;hveNw4O$4#=en`%k!aY{SzT z+@uFUS=pu4?}F*Ov=Dd#6-p?(w$iH0r-OBYkJl)l>qsk#Jl6Vc#38D&K|%6ye*dtx z2dpPvt_Uazry9|V0Y5B=^w9&gq8lPL0Cjc|P9Ctj1GwPEI7A&>_cR|b0;mfB;-e4! zkpvsV#phq)2e6BYz-g-z2~FJ7l@*paG%h}V>p#e?^X=D;sH_{y$lE2QO{PNSajwtv z-8tC1e3wv;x=@0E!(J;4RM|o<1OX|5r^bi3naTq=@F|Y#W&wY5Brv?>XlNn0`{MA& z^XD5M15HADP+*QOyL0{3zE2vVllt}p$pOFyTCu#@1axVc@&m6(&}s?6TRf7}ztGuh z+mCi)2?*O2W6p||GQUU*)2CTYnG zm~6qUJ~msa%{#5pjgO#`u;mTeNTRDa)R)nCJP1|X=#+RJ zt?LIw-~c;Bf`}kCAbs`p)5s<($n}vW(@$F zX9T|b>s}mzb(xd5QHxzt{`hdJb{WK+mha{P5m2$-%%(U~{;?pXMWxS|nvIPeXJ#0E z^W}S2c@&E94pL6d*|2~Ov%Jj?T2GU0a41kXOF#GC{w3!u*>h!Xm+Ao>%vZLMIM-77`)-_ z6;Va^F&+t-E&ai5&^Moeeu2}AO*vnoVUcZtw^9r<`mA#jK#PlxfCX`n8v#A3uMU(! zAClZi;R_l^M)+jSEZyg<1W;h~Fbt334CM%72z4sdBESz9vm9X|9}&W=O2wV_bN0n7 zNdgB#-rDaR00i1y?Mzz7v}X7HDRI{u&N96u=nOSNsF>TsWkE|cqxSEXTF8By$0t)4 zM7JSg2XKuHJEd>SGRklj$RDmT$4xI(07g0W`p7tWSIH<$AZUlVVO=rvlT9=X9Z=RJ z^e~WOB;`2^w;G@DcT-*+5-=6wk|`+SJJFfDNS(Q0y!26Jg?nclN!-lZYT>qr!G^}( z-S|X*9QGQw#)UAcUAD_|}@OLRVrt z-r=cuYw=3BYWdic^rPCv(b{`{8O$DUWl*O>k!%v>s0tSIlV?S9^q7S+=65+EMbM+H z3Lw^(Y9JcY=a=9i7QqcTrn*n^zColssLm53RT2ef21-QPogipcJgK;Jk88Jj6_IToLasR!*-iqQarjnJW6OjwcR~d*fC}hTkUQpC_+D%+Z$cQ zKy~kW*V;eno;0gC^f-k|Dh>R93U|V@3^^11Y^AD~AO{!P?XCiLDhx?QDX^VZCAP_F z{8W8nKjJ?Hc}3ix`+j)c*qVi$-mV7sOukA-a;KZsCXu=7<*0(;z526PpDP?WdIBES zOw(`YS-s%eAc5bbeQpPf(Z1o>F^2nRfo1MscqpE)Uy)rXPoh{lg82@jR@b?4l_^x# zR8%PsZP=(#3TvtnDr#QBeyoogZ>1)knhKqgdIbk-3qab-^7C#(LI&7`gf`(>QYzDb zd)S|oM|&D*7X$Ppzo7sX))ldHfWI_+Y5&3HJFysCXR~Q*8It+n#@b(|Vl{rgKw161 zVXb(#97}XCOgjAD4B^)8HW=e|L#=H?*M7k=8F;wa7l1E@$_Z-sXon4yaQ+6ml>T}> zgA?bH)&eIb299UA)Tna?a8G7m4H&0g+zb4!QfA!#YYM+`vK*@-_qX`Bb|3< zISvx1rq)(tM$rKS&ya`c*HdHWUv?S6YZLJb=G``M%zy{Yt@w#q2zRDsN8}d=tm)tV zb)vWLL8Oh-u?TU5rSWHHylkOuUR8$#VAw6b9+9Cg_%ikfvK^i50+Sf<2qj~cK#Jj{ zSsX}QE0$S)M18f)!X-E)btnJJCTIGZ zdM{FXZfmTGvY5b#F-bP#K@Lwn5wG9#hSY36>YQ{^UFl%y(W*3TVgQAitt=vEiozE# zyQLwK2p5tmK!yt{DeGk(IvM+89yE&fmOz907|vym2E%*3kVHRZdbLdj9`oL!)mw^V zG_Xf@yhT#6&jp$0SL7AB1WC{}c>@t$6}PzHYP6%031fV_gcHLOfqIm9?S{5lY>PDN zG}2(UhCXAvT7QH;YDel{TXUxPa8tzzwz`v`B_nWismNmth{v3(`mP3v$GND#(Q^LB*NA2mp1CE^{d9ZFv6ja zortI%4C@W_tpX(L@I!~)uwt9lt&-#^7`a#?T-P5Ij5WXH8~rVp#b*E4gCpxWem32} zAOhFmCLnsIj5s$8(oKDL;JK>c4xQtYQ9yflKDZcv1;W}$gF}FGH%6{WYl|AW_ zRT8}>S>qm>NL@SOW;ed9n6)~A9Qdc7#`Lhho0KHTjO0@VP%u) zpXd)?Gy=a@I-<|5RfIQ>u5BNSKVk7uzTpBvd5v@9zf5-oy?D}Pe*a9G{5dmj^!;L7|Kq&tyVo4QBXW%)vsr2EB0a$*`DdB&Ps)OC^Hgu~ zlP=ApEyXvQZTe(Q1V22n+^#$UgD+$#xT5r-8;6=GrLF}bp-8WV#e5}L2w(j{Bjr;0lZPObSD1}MXiu`u`E#d*7)r`;! zFDisYu603RV~QY-CH5RYq*IGp7nYz)X7XL6o6)l^55ALk#`esYTn^WtP`Q;XeU_OK zyLO710LHF`Yh9ldlWV9bx;x8-L!+MIOz|(!EQe44NU+)OP2dQfEv!6U&~u1)D%ibD zvfWfBg3&U-Ci7O)VrN_x+S@IpCBM!OsDE2nbnaG7#%%C zt7SRfayAXDxGvh~2TQML7aIt2x1Ho(+kMUykJDxaZQ0yuq>Iz6dIs@uil33fdSn5x ze6N1ytq(10+}ebG)?myrE44$fKCT55u z`{Y)0U%IyE!OPO&FWpBP8>pC}6G<>MS!UHk4jV#=elq)Ol}qCQoMoOmZgSs%L=O8;xZ{iKP5K8mh#9fOa3;e&J8q(aO$+IdvK7mj?PIXEMrt zJW7b0x?kUzpJ<2}0q@WQk<=Bd?X15X=Ogoq|h{&eJvtzor+GRZOXWiXT@akux{JXrPp0d&$_w zYG{tO$|L8nM`j2eEvKGlbWFT=)7Ef;+_cRQj50EhAGr*|ddS8z@{}Im0l=kqx}x8b zH1FD{PQ*o@#fT)nVWN1v2FU=@ftjH7gNV}rlcR^?FVWu<5tpdT-Q2nt+bn?XHuK1> zvVz^NlYdpXn+@5Q{-c7Ne1T&;r;3kK+us&hygJdBWhQA`^g|{^#6@*Q=B=V;*1C#o zxn$wWnX*xGcq6YQn$_!8ehss{!tClMd|wVCTB_|`&AC^0zS$#9JQZB}pCTm3_CEJHd&TM5;Tm+wmR zqw*{J(j>|kIeS7x?0Ome7Ul;L>>3zK0Ba>G+y~;Zn_$-FCud2aYH4O)oVs@rIt2-s z2%xjn&IMI++W_^wU#KrNJ{uXS!j*9Oa_!w~G69~|$J{SS>~=>Rud#_$0s%W}n=7oHT{5huYvo4Y8_^arM6{|sgGhfNKL<~H=TeNtBR+g#B>_bs zc=2|A7v{k;pc+T9lkj=kjP%FPwP%?ERS9k}l3Q6gU6sNIuC5;V2%)=^YKld=-{z_e z`2jGz9<`pZO+*7Y?fFPQSxun>))L!=(k`0Q+66TW<)DiA7Ps>{{d(rv@(Zv#%* z#^nz83_hGp@@cWY8vQKbVK1GjhKn?hJ|B9dpSe?HF6lHGVKW`!l8889yOYw{IbC~r zjylHMJcYW-hj<7KYAvGCx0(I^EJY(S$+N`_zG)V>oV?y6{HTc3=0kZ_$XP#a20xP^ zBy0eIBbZ%3`6Z~`VpIM#27aSE?pr|cF@zcFZvCDg;pzffFTqG9QHiBjgd%j~UQJjO zjK8a4kR3SEqoQqTbLdJ0DpY)Ra9Q>To*>Q7llPm2d8&ENbaCPRzTy z_RJ%+MS%TzbGwGa=CZrLs5*N2-cN&)W%LAYjOckaf(W83j{F(!9H>BLQG8VTMe+>g&|Zomz(}$3{~E z+oqe{qIfypx|qC5^Wd#z%Pp~`QEynaO{=$gFp~DqM&7w(rO&CUO8Fe?^kk}8o)2t7 zP9dsC&K*~{>s#YfAw={(&`l{kfDKiAVgN7v)^aP@aji!f#9}$vG!F3SbXjRY(<+W z<+Xf7*wuyazqS3pwf)ze|LR1d{@VY)iL?LAnAz!@8avYcv;2qMk5b;1+oXs0$!+>W zVCzH37cr4XC^8pOttg_Pgw8EP+D*KI&DEHl^00b)Rm7|?+QL2De%sUedE-c1t0Q$| z&2LUBB2CCgj2ot0lRjpsn0a-S<)(Hxn@f9Z4!a@LG{-;@RW2%!w+JLz@tsgCX_1b> zmu!sR7*z~!h3)_rNRJ6ZVjRHSPUM_KLj^yUDWRfR=w1GhVnDgr0iqvA%ngNXXHh4m zT_?%a5?^Bm$xx1LCXa=0xLVAXIRbLpR!G7Fw4O4I!i|@JE;Gd)y$Fz)aT|%iqF6$74d9~aT>Y^sWbg)?!^H( z)7@E;duwG4No_bDN_+<13pfdNSfH>3LptoyImQTcGA<&-hY1}XiZpxk6XogBmKf`& zN=_!BR8{<8ze$ow*&$;2MHkiGZ=oizxGTo(JtSGr4Q|}54n#|yEl!Iv(G_%Ma$1c! zF5YQ`Ol8Id+b}KMuahPLQXNCJNpZ^f-5wNC=&9kCd~H&n=IXgcRO&peE;+qh2iGXp z^a*u1broZ|q4He1Rl7@bAKa+Rq7|8SE9Jzkhah{SnSqHsuu*gx=t3ejr`_xsS6n4y zICbdM`W&Ddx0h5sTLt;6=%r{)rTYvf5#2nVX4#WJpjqVR-=1`>XkRhAb*Yh?4&qZyQ4Z4T!_O4Lf zG+&4&1tq5=h*Z0XRLjA>CK25ac9nm7si+kW5{qW12JJ?`(;M5rU8nEug-4Ko^%4+& z^%6M$TBrY^n)t8z-G3@5x)P=>{$|dDZi9OQ*F0%9zw?vE+LHupNW1|Es;w0+!6jre zT5l6Nh-qu+{BwqC?!1_At5Auzo+ARMo)j)*#G{n85a&*@bJ*o7#Hf_^fjK+Oy_*;p(YbJoJW_EUI;ip7xL5s5 z3dUJA__xk9^)`j@ALy(tm7m62+vRs2vhx9mHIkJSde~$?y$KO8xTb(cLA7K6$ckiEAHpNX^4Dv&Z zy!w9)=6Ta>Mj{H1?0`1V+<-$H4&xrU(_;#Ly`m%u;xtS@5IW5y%YF~iUC5?uLt|!C zfQj^v%m+&hzS{k;`yChzn5CeL4@yFNx9(>5m@$Z?xVeNU%L7@aNlAzaw=lU6sz@Un zIYh5#5;Dl8MRli#*HvH2P5r@`vrfBUv=~dR2W6>}n3A))wTi*6EpC`U+#Ux6vc8}} zE*8zFhE61-#Po60l%VNb9XY`nIhhU19ChaVw>ZQOreC%Ft%3TB1OC5o_z$D^A1M6G z^!*b9t=U<~0eWb#yUsnXq%CbWIKl=OHhr~uaB}Udh)cW-!jG4c%tv%VAKe}ww_p+O z`ZzfSfz>8_`VHpyGvuwB(`^J06(q98qAzWEA5w z=+G<_hDXyp$$FHr!{b(0gX~G4Ej(inmVP?v23g2S_80tGyXlF4uJ)`Yl5U#oDaJ}q zfudZlF^{=JsnZVXDBonY2kHEmy0uj1@c!+rNxU}>D*n>P_1FLG<}>`$+^cFkZm=VJ z@1}plZM+D~k+kS%HYNT#Z_@)};#a(~-YY*u_iwHzi9MQ|)7AA}!`I(X=OZ>e&vCrv zc^%yH@|b3-6N)mF{HVKhgU3&pVq zi2s45jkt-?%LjgmQV3_$K%y&2->Sml8KA` zxVzEyWw2`ICE7QBcjaH1Y}vFFS`Dc3`K2x~c7gm5wrX6#5P~G(laHegI|5<5sF<$n zWc``kqO1O*l!3i)SH+yP>w0h%)jhL60A{ud6C~Gyp$PbE9FEXkX!iiexNXiLLzT!E z6AXsy`uo)dYUm!0x$ttMSpkGbljQuoo%A+cBvFIva&fUDsl@t81NT|^Jw)J0EK+YN zp>fb`1ZQ0qF3E6xNYw#TE4;Gu)w9VEO=&N7n=rzVPmMAwz1K>lpV1==y3n3VGCrzg zyWNXT-0&nwuxT+aD&-+-$MaJmE5R09`esByX02R^gQW4Z`nBJK*P?|IYF&bC!NN(! zw{){H7t`Bn2&rv7LUbGSvN7IhRd~EpAd4jS(4;p?K~=b^FTCR;;=PsLE`j;aW%Zg; zj_CrlSv}fhX~xtb7JP^{ePt^ty1c42bw%3baoTxltOgk*er4g1)Ft1NDF4$J)!t3bx%JOSUl%oq6nVW;3Ey zrcH`j!@{Xo6zVlXz(pSgZ{I;FD~y4POc;gL%*cOKA0le^6i&H>9hDn+KoX0;AaRqk zmEM^Z~Pl(L|aTdE;cL`X#{qf=oN%PC<(*QX4{Bblw& z?uI+|6O0SL(zDPhTpc=I&F;R>NPJ!lJI;sP#WC*obrk3edu7s;^)lXZYUJqXIW4>Y zso`lD2)mH{Pr z*vAUsx-K^aC6?YbTVt|=B67s?OHLa&i}^6ZwAMy9H(<`I>HK6ImrC+=-q1eiFtghG z^?Zsx4ZYQO7U~~rScOW8XGw;4M(8k9RnsRb8EN}Vn?u1sp22(cio2yG>lAmcuW#U) z3}#C*Qv#LvGrV*mtlk^Z!neP<*C9L%4%+Yf`Gc*Y*Iz2|=xpQ14pSJnhm7D`M${_a zJ;`Ndw@>6HXRAi)T34NaZKYMh*Xrf;WYEsbi;%06#73{dZ)3nsbTD_3OsXE|c5t+D z#l4bX(?z}Rm?PmGjk85gUYehI0wSU#3OovmkOD$`5HvEFK$4?L-e@#{X|b<(9Y=yJ zBK)bYlTT*8>12lpKRb<|2{^O$Tfx`G+tsT{)9p!J3DXp*(eCcnl3%=z{-m0{oBb+j zjp5r+P>}Ou98LZwhli+?*`ha_XRZbyJ4@G2n=mvPv1C5EY?2C@d+-eu%gj($iOj@;ELF zmHQ|SnenVzZ-HFjA#TQ~Rm)`jXZ_De0-?MuXo3j_qPm#UcJkl+3-S6W#WO*tH)eje?1!dQq@)hzMI5ReYR8@E0=-kCrf{tW>g-QFRaL=<~ zG_Pq$aDAq4}P7a<1UL%#+f5CfdUz3ze{Z4`O%~w4G3z7-7$FF%YAPePL2W zqcZR)HLZ!tp;9Q1TFj?vT+C|ZS6VpX+TlvY3M-8#Q40a7l#3SXTT!`xh&9*%g8P%iUi<;Kj%##A=R?J?7*#UsweTXk`^PAk_`(L{LcNrr&=C=+6HUL2M=D$Cb z{d1ST(l%GZ7Hj$bA>8rRW5&aj$t!soCSdj-HZX__0T)l<hUvse%itPb@1iodsxPSs~vAwmJapY+oKs< zx2SdVe0lkaaQ(+HqM#LL(xt_gZ1G*Z`*X11!NntWO5sMOqb-~IcJ%y!lgfau`^_!V zLLm&riY{T@D12mRSNitG*qm=`SB5qrdw!d+T@KZkxKNF5)`rw|-23G=x{$|f-R$t| z5ho|1RTOJ<(cPiti+d2owaK17dwQaGCQ)wkpjM4em#lGpWHWny-04TZ>E6fmC>n+0f?*UDc^PPI-ggoXGiP%$<^+unC&dvaq(;C zXy&X79W8yZPHCgl{nfjw5sz;T+UMb|NPaw?u6BhFQE<+8Q)g>0MTz7}K=q-k?Mna5KvE$Vw0X*H)wg`s!;l7Mi7*{JZvh9BQHK1=&k2<$;_T4axFgo zdA0Yr|J*Tf(B47rw(DWylrgbg;7fQ^W|<`QHu&vgG+s_eBZVL{EoDzxTnD;ZkK8In z(Xdz2;+CxVJGZ>0DdoVGLIkyH7J%SQx4WxtQq=o%In#)vJ@u>wP~h1<1puOTS!vVZ zSTW3g1&SdD3%uSsxE}2jRR}c9V;P0lsO3;I=33Oo>K(zeA_(2}s+|Do3tH`p-Q|iL z1ae*Aj47?4%^+5Y``A?ki7Ez|N_0?*%E8}a7hXo=$dG2OY3!twR1G{og{i$aM}AYP zrsT2wXj+C4TKMAnh}FH7Y2%YS*KgKV>!^&cMIdZwy2CR{r#F2IxX)D-SsOCsBASOQ zVSvT~hu(-pDdvPNDM6m#^rIda*18jyyy5;_aZTM&j3+-W@6GWxO@Ws1t1tAsueG2r zFaS|NV_xm`G_|+ujiEiH$@o?&-z@sNinIFtBHyYYI-B0XYu4FnGNKz_bwS=!Xr;(* zYfGT_r_1xJcJR>kGt=$Ki=n$m7FE;C=qHy?&ZIY&I-$}C5QbJ?Mpc*KS1@187d?db zW@{d)Tg|~c961(^nZ@(?&H2f%vbS}a1nSZKT}Dg_=C*rq&q=3uv`i#626**NU@WCk zSi{lhU=0!lV;B}}IbO0zw()CQ{A`pTt(TTA@U+l|`^(V4$Hl_I!SBVZNvluWPhY=c zUv>Z`y=+}rg~d<(?MuX9*~M6?;@SyDbP=IgTxmX%)LKWC2m$sR$PO~7wLe8p5-%U` zrN;G)$4;t68b7@-%@}x<)5^~wtgYIUA%a&Xj}o3jO?t)~v`+6HFy|6^cCg$5oQOP+ zl0S2_q?{07Htpi3_>BQ=LUf39xkayv5o#1Q@WNh4VG0ETz)le|ymb>|j4;I_lqQQQjXMaO%U(lYhF3oIp$kv9NHkK z{4sPewe65UW>gKRRJU&m86cm!670lFJ=Zs=^U9%K*yIv%Kl1R(w9z}>^~sVE&hO5n z5WDODQClOVIPxid>D~VHBnNGr?fcg9wNcCkBuxMCg4BEvc9%$+k*1}$h@+ZVdQzXW z_y4W~*r>PlOfep%)rJE3q=B=j#~buJZO3gzQM`KHg19Kf`$z%rMJa@U{<3DP8;7e_ zHUxCB>Td?E%sT`z%hfXCd`_(?*J6GX2uexe8)56=Y)~feHzxLRhOR9IabY3}s~xJ< z*>V;81qPxTV<7RIoU?OcMrc;~)MWz!t>pDNF?pXzZYym}=qy!K`;llhhDXaNuFgT| zqP`LRtcayQLhs>~3**X$rdAXk{jACW)eom)IU3j-8}ah93yx$QICV9w-%-8_3_qEJd%L9|*Jaf1}%ldKPKuJms3yBacax50;ZVdGg{{@xIkTQo>>DuWz) zsy`|>jMvTYd_Z7I@@zC8Z=K-{u)Yue1Ly`|vJJeG_9_%X37Fj59)Z+w6r$}HPa8D` z8sQTt*dP2CgdsvfU2HC+VfzonzHfjPBXt|{uH*@jx&AOfK4J7XKtZd$+-R@o9kvD& z=8LzfDFmHxT@Gu`bPg{XFF__pH@h*niFkpCPt>fEM3%#H`@{-+W;BLCu#axbyjojD zVOdrQ^Qz8f33GOkM)|}oEX$OII?6*|e>{yCxN$LKj^qWxv-;&eYVl||Q(8e>eL>MZ z$Vl0JMGqCFMkJ2>>;7gaQ?d$$jV-o>1r$)nI*wYzaq_V-Jx80cLocBGWZ}!J;`;$$ zQEpiXC8Q;GGRv^Ny8hQM@w7fGR7{!XJ+Eh_b(OT-bcuF)KBf=$wA|1;B@TkLhsZju z3W|&+_JFc?FJ^XpN{h{YD~Ij*CulcKDkA+iA(fst_5KL1qrWP)^73}IgH{P8rTObS2{w;{YvHep zV{Q$U>&wE=Jmj9$mk8)h#D-{8<$_ErUtvN@{l{Ya{cod}dIhp5sMA6M7q(9GsO@1M zFr0R&1WX60RN|K&b=U(RZn*tI2!Md@ItxZR`T?xbu(}2Vd{8GbVfyqO+WG?1D;v!` zx>X{_HM1wV749Je$9+ua1NM+{`X~bw{CB@Qb;JzIn`-bR89~QF_&{@<#mH69actxQutNRuK(gZhk>n!J6m~ezj z4gb#fyAk*q`epq}fxUj{69yX9eU*D2>D2r>v18wxR$(^^R+u+hR_i{^!8F%ZgL?Q5 zk@*d~QARz)Xw79blBz5Q)1e&!+y_`d@HgSd8Mj5b~dNG>m6OM%@@5BY-b12 zW-D>zM=yFuUTY>(6$iK47zsR1zPhi`E(L};%O9F5M;Nk-{T0@%~H2-7>*2>`X59>HkR-*xoCYix+3)T-GK zbZ(zs2rwsvh*0hEpv?6r@Bbs=ihgQz8Yjqt} z(HaJt2}tT|me`?yU%jx8Ux?>bn?K<)(UPYGHE6sV-qp(^&#+q#dnvn6tw|mBWDenW zwN|Fa%k964n^_s++eVLcA{~*ipo9wu$OqOi@pWwMY(B=uC|c0*l}Q7Hkhu_{Ryjv;x^$s@kTpj1W{f5Qr^JDfjXUT$0c zbA|11KV5bu8e3*`Wj2S0;O=cP(1;It-l-;`eH{+ z?OWPJwLurjiDOnLMJ6$6^6O2A@0}xW|LUYrFAL?)H*Nq-hEOcV0DZQYMu|9R9?SL0 zxetQ{2QWf2SB%n?K0ufk%0Uwq?+JFx0=R#}d?&g0BH^=wye3N8#yb2f6P^(Q;d?nF zNIA|oE(DEe;4;i&*c&(wn?vzev*3c8JvvW!41Sn|X&1D%`e_NKOf?=tifatPToKr} z$)CELqd3I3&b4TUrY%cSupHEB-pHh5UWtP2`GiW52M5* z8~{P``?G&_I{Q$_Bi=ZzqiHMRr` zZ8w}$$ye9+6ux{@k;hKc1i8NriE|m3rv$1Yv8>`J8OM@ZJ8v<0No6i67$HQvQlU$q z$miIM`XPcsH#VBo7FlQ#qKxaSo%pAM%P+WoIkbv@M_u^Nf=mH~kb~PGsg4fRzC~Go zTA~Zy!(EHIo6icMr2C!~XC^nk)SDt_f;G4@ow!;MI-A+~&L7J!QcETqn@HY14S`~{ zgnWgc_p}O&gUxOS5Eh{Chh)+qDnIUE9{n_qLkIi)U<~vMt>7_G(w>I{8{uV0(kM2N zJV-S}Tv&LiQ@l|)=TNiBO_fWm91BzTxC3zvXo6P5!l}PWSW_)vg|4>FQgvB|5o?@# zE~fLCeGK#(BpSTNO03DX8{`R|SOZ ze3{&PtX4Ix3UDJAwdv07m!$M4aBHP-3%=$3tN5n)XaFo84H4%f4`qen@{V6ZmCVov z-eT3N!QpaoCC8#e8};O-0wn!olbsJ$ovD)#z5N0wJ^(0bWQ0w$j0SmPlKnPD%Y$udI{ zPQ_N_oSAilG;1EM*thd_;TvU*DCQ$}#6ij;;ZNThTZE~QrtF4l>6mZz9L4hZ(Omug zm8+5C+cGZLK|T)`a_0xV8w8D#s8~`&+yxLhB&!#)spyf)0^UcOV7eajB~B~RBt-E| z1htlEAk5$yOe%^pJ#w`AFNyQnyxi^KqNdLYn*bgusPO7q z`>3RiC6o9ZbI+%TnfeEh`Q~(J3mplP`_3^~@&r^2Co!jSI*dP}#PpS^lQ&z;ZI}rz z9vHUe8NNa?=M%DB%n8(1MhHc7>mS=P;wxaunblhE{Q}W<$eDAeJbkjH)*7?Mn&k>Y){UBjd(Ejxn|-6D~V)RfY#ZXF$|=jln$jl z=skm+A?{9FMJ2uOP^TUjNWD5m0G1Fp%au)xyqcRcUEsn}6Br}zFW|>_TZ)a5vEpVc zxbQ+Ex8N}Up>VDJcE%wwNuB=!$Vx%3UDhCqZJZpsVaA>~+oKW%1-2r-St@s@Qt<{> zCHx`DiB4Y^TrnZj5E+%Zx6#oi5qA9n%!aUeWrwd`|r4b z*$Ai(8QxViOeC(MvD?DgbN%Ign|Y;ZH#iCoEnL=zTY+XRlQWFaFj)GVZ;;hij1XL^^Qw(Rfj zB!mPgN&VU`ozF}-I}iwyQz>M~545K^g^`!BvI+<dopHC{MjzcC@~RY`Od)777tS+su3fzuHTFpJYZ4+bj?Mjh=ISi&qUAfV z?(kR2vgMm0E!c;FdSaO8S%hTPjIG!rRRZ5g(|x6klA^MN(Ohei9DFK~S%y*OTr8t! z9aO_Ou@ORfO5ug#Oyp0G`U-{V2h|kvz!|DiE!T62R}j#;lmIm}B896vRHGK}!2N|H z{D6T-KPY<{hbU45kD(#5(x}m4p`hX<@PKXV%i<4`b;ojE|87;r*wG)$`Zk~BZgO}% zb7nc;=EVzJ-&?Snj8R1c*=X*~lr-0#8ve5^p45Yj)Lp@uVH&bR@RCYqU2vy^)0FbA z@b@NIf!b(k@e-t{^F9nu`8d*jHcEZ3>>@7_TjZXAyeYvvS)2POQvgJ-;BAERHuF# zJ~y&CRm#3^V-DjPuRcn9N%^UxbLSKua zh+1cgP)L?2GC3MTiBnr39F`N-b1*3*rokh@GMafjQc^L)P-Lb#uMncw&-#turo^~v z-43lpD5&C~Wo2$Vl_>WjJYwz|5Q<_w02Q*d5sHGiNM<0?2%|C2VXc`33EKB)=3?U$ z&oKPgq#*0gOYI-?iC?wF(K5N$K4>{*at|Oj03$^8rDhjtAsD9biwnyh2y9DoV0cJ) z3((KU9`uV*OJzc|ua{M_1j55>DGzq^mO7L1gCBszS7^`T|Dr zp$Q^uVX%$Jv3Eu{wRju)R;)J7m{_S9xIJ!F>weT(Bp6r30Zse<6Ung3F_AJPNH)x> zKJzy7873${t+cYnxWl=L;_xL6vH!5Wwd?2BX?wyJ)3WI#t-8N-dx zNs#5&mZar-AOcKTV`Kz$JMM8C9HHj6dBxNb>_{Y%?ML(YUA-gXPR6)Lj@W?hLM6u;vs_Nm^j5rgdaWf+UIpz;Nw7Ro z&qxrpU8+OV5*$mK0wc02Go(G(UOZAj-uquF#XP8SpL}cIV}COYy3#G`5*5HqH#J($ z+!A7U6Spv?)aMcy;so=q=%Uk{Avw!fa`@rscN$J<K#bPgg;q# zxdBp`30r*YHuLirsX;meGTGE~V3#0mxuoh>aqw;I_nT!vp>u*FW@XpVZoxTWDhWA< zSgEE3aRc+vv_Y0ldR#67kV%eUIuc?>A%qu)Va|M`X9i_2*T$pM3!&5ZdhU|1*Vx*{lQeW|P&;E- zXJ}}kSNUR)#E!NRpfAG1mx)@Av=X!hN`t2qG6TL9G4N~lvt2KgKWJwQh#C&BdT<)J zGNA~+fJ;ZN4qN&rhIAHv01vwV49m7R>M+#%K12G;#vB!n$oJ}6McT-C%>j58?RxYx zd;#G_N;2SuYzvC}#cu_0_-a0ts7UrfKq5%_;UFxw+ipt8GjT9sQKaZXe)vK}`nvcG zlZdP_-`1k+8lj>Tda;RFe!$&;d`gb97?6i@r6R_Ri2a1?F=T0y@426H5_;yvF{{&_ z@Vdmlw2TeSYsYPE$QJp<&%?_W)GTb_(@rTEFs!9%osa^5`rxh}VWzlN6&wcL_tg%I zfWYu?VwG{eK}pl@j+t@+kz?~`pv-H2AUPfHm{9~N&m3TMuV8pF5x${6(J!Am^1dKh zQsM?XKV#C`Fm$tH;fqS+G8CS+xcs9|RGf7V=F4(stWws0DOP zRUSH(3%)N=rkF#ZDQvFN6K9^hvyr;Z_a3j=@K_2mY zz6-?IcNTYW{0^-cQNZqe8<7Tj@iqH%wnt{CtM=2cWeKYbj(i54I+XyEt=_E+^;<$Uu=)L`!#0FBG4@Gq-br?tlWP{ zp+D7q{UjQ>O9(3|`x`G1u*{jq@fU-GVYKraKF?`=>Kq|fhWS*N&?94*B&T7t0tXq=1uC-?22Gb5RK0m-UA0W? z$*Rvk*l{QZYCxS@j2K@HAWtPW9V?d#d{yZoq3W&Xc*{I?a!0g3Vw8VqoRY@m4JgWg!nQ?{>9R z=VGD6IV59DS_g^B*GY|9!SKJ`2nLp?T^*<0h1JGo=kJ9sd%9quzC5%QZi$ShV zsceD#YqXdwD$~3A^9^d}n{vHMlV9QS`Kii%qrT6GG_GLOc7uz{5r>j&ipeca)exva zgA50M-;x9sruLKV>VRYlLeI|Rx-{{_l=kO2PqFl?m@DEM!-evyiiQmHcSF=BNfk&V zHG#Q9(d%gK=JKa`UXHp7h*MNqharkl6P5fV_Ek3Y7>PM^bQBa+tF{vbZE?!;q*d`U zu#08+a;8ZTTvDce0bAJ0nAS9<1;S=cQ)$AE9O{KB9sB+6cfTaV!Aj|G#=cm@K|0;R ziiN?cs;+I72qeT3eyblc2F8`~OyJlAS<^+j;R^8#tookSkqeKh6?qxJiHm8QjamU> z4kV;;d-)C%UpF9H40cN`W}rF`e`$t4!D2781w&ZC=Eqs--NG%Nv&FdEko z`=e;%A6*E91Lz|X>3A$Nw&Cse^2HerAGIR3dmcO<$xWLF+5AtzDl4MVC^S#Upxwbmw1t?NQ|PET*-hwE4iOi$ZhASZXhB(ZfY zx)G&+nB7MBmDMN7E?X;Q=Y+dwM0|LL{kMcH2}AFHfB^#X<^cl2_&XsTO^vLK=>ItW zxu%c1XuUjq-Ol&wH_2si5{|s%Uv~Tzw=I8gOD&f~M=@VQA<8TK5m}hGXn*ahz-Nl7 zSD0ygP=TgT+WHs>*~E2sba5gj=+wt8oxDdd0n;uC0rG;&?48g71@6FsBm0+jXkm+Y zXrvMY6hqUd?5+SnH$CCYQ_<~yb-M7SnD4on-J2L%U7ZdA5dnbgn766j7^>jPHgv&3 zm6IZi*w66*VP{ z-;>_p3sKgpn>gLaY(w^#!L{}E-bYYJHBb^GLOM8syRr>)-}CnA-XgOWV|H2|keCFo zFI{jEU8d*AK+HJ6^v}&Ky-FV|f(v|0MG>smu9Q>!iq6WoQ}OX%4c4LMf^-kNLvkP$ zex8F@-L5;$J9}a90++5w60}irbQpiQgPx=bn|UOt&&MsDw_Wy^s@?t!YkjC;O2uN2 zL*-5*8;+6}LavuG(A&L+rl^2Ft1PSwZ78qkrCCq1f)?3zBTXA4Ano8y=;`_@M}Sfm zCG)iOop3m_ePT;K6MZq?lWlkx61!$EAO!0Prd(SEA+*Vt9vK&5ddHJ}^0?5;(PI;o zKe1UNE|ie-mF3jCDg~5P&6-3Lo`%a-sJ9V*T?9sm4bG2rwnh;0MN6@wxw$o~a7$bL zpaiB>?pWv@;|Iv|R)T_#Q|b<*h1?>roZ^%Za^^u%rX#7SoTY|t&T5Jez86@DNNHUK z)VGkdCo&w9^8+-abM!LpDqnEeOJ`lQ6`KSnh+zyjidEM9SQZnG zS1Ek+M6OpBuDvL$TOEM$SV~VvyQ#iZ+bSKZCmU}RCoMK5XTvkoeCMA%qUgx+ly=GU zm4V34C1io7NHBl9dzzQ(4Dew@{X7liBx$T1WTPBDmr}fF&FhHHEnbkZ1A!^f@Di5C z1_Uh^I@rb>_vH}w~hOZT7% zJH5aPq4*3dZ&O++KXur{Bv27Q09%|8m2r6p41SU2^YXm*`XI{E22x}Il*GQnXxp13t_i;(ah8uEnQwyM#umBU%a zl%0NLfDvUpuL>`}dyEm(^Cb}FtDi%FLvYH38{8o?!ur&)Xz=i%dIybL?USQtKhT3| zijK%Z#M^3j^XVks3e60q&qlu&rVWR|C4r4u)-S z|G_TR$HjwWCY(p|gyeH>#Jv&+JAT23#dbEqOK`-ShwZ1&!Q7N5bu|1vMk*Iw6Le~j z93#_|`@jVjv(NV=pT2paPUL~Kme?ka$q(0*F2@rG=O-$!^v^7Q*n{JMp~HG?_m&`| zAR2rh%9P_uP-J75B0>6gFx+nX@`RCm0CPx7$7W=$>3G6RHKDJ|FG13yx~q9oTHVrz7PK-lc%^qR>l zveE_$t8^Uz9aK6SE)xgz!4V9>s(~fWGJ+iasOQ?GWnWxQ$3WkO$;s7Y@1bAZ^};A= zBUSLiS70yd>I0{MSLF9LhsdEo%}&5YPy&?&G2!fkBAvpjlftkwN*7X{DlQM1MZT!PCg4n{WwR8#fJk3nEvrcZZ6uLEd?a@tIIUj(*WV5#2?OPl^8 z_e!3z3@)&(w1P{Vv8P?Gzh*@><<@Ao6W^@VvO`Lp-P;jrCMZ>`J6lrQ$-sE9&ta(G| zQM&kpA=|)uh3O>_KeDcSAJnPO7f?@Rc?lGs@^;mbtw(` z0zMR7mGR;$1BhyBo6)7|+{wsdIqd>==2edgT`YuuVy@=j(854|H~~*7(zZ?Y+Tl z3t4N7o<+crBy?%Nt6a0xSL8{k2pjhn-2iRh zq?kwwZ_jU%uR}%N>=pKJ8@8G(pVsl?vim~%OziobX*pTGth}^22@awj84_BV^5fM` zpT>93vARy;%z5Bt=h>^;ne}B3U*aS_V|VnXXkgJ*!GOUs4GivONuZ8}-uFWN$_QV= zV&+yz6Om?W8eSV3Z-j9)yAokp)^U);scrdoj~C7Qed?O9I0`1y)9ib?XR%PA4^T0_ zuxs(>Ted*xIF&c4d**`0W*gP&ysAzfK5Y__AtvS@>zB^WwQp|+dfjxnct0v`<;+Hr zuWkF~To3qwKC4yvWFS|G~aSrDRso@t?KduA*)9J)yZZM zgKhP?e=SX=QyO!THLr7O{KPxRfQ*m_SDnlVcq$rh1lba$X$rUK;$it5@%3%r;eQvv zenb6GOZ~={%h~@2w)}^T{YdkTEsJ4z5q^4kqszo^bh)*A)_D^?DTAMY8illGOjuAs z=6k?PD8G-4!HcoZF8!{GojkgF5VQkN|Jz)TqDMt8tIbW8ab!r5<_=kQWy-MO; zA2TJ{XTxvr==UyNaiH1m&<_|};~6VyFtXb6kxu08+2aN$Og*ohBM@--6yWXjka}bT zEP(2`jQC_{9LH=q-N9m%1hqavh6ngsh_^PdF8gVx_5+y?2#=5@`{3NchFH_`&G~T&BHZjQl{k_2{`0)| zV?zp_R6s_gVVR#1WR&SbBXC_T$P~Qb=eQpWIiS3iC9HM#j!lEcx?G8VrPZ)3GGHjg z21uQ_wm%*_HZ_B3-6fC!sg$5aD*K_01 zl(1%*JLqB7_7zTDu5NLdvYb}ZWqtA$Iftn&`0fPq@51vm1R>`P6&oSjfkdxyT51j- z6+Yb#fZ)wq?2mSneW_+Iz0Q}cV=pyAI40c(fe*)>AIsd-94B;Jp~_AMF5VY~|H*>| zg_~1L*%)JfLg%K-g#^xF-m?mGWSU8Mcg{D-qoFUCr1%Py%*n|s1?$^ADkT)Q2Fn-m zo5xrIrj^)iAyp7y3QXb93(T~KjqH>x_T`l}_5XPF+yIXH!E#l+M@a?MI_;Z_0JBn- ztCV@xNJ+KL`N%2^PGBRT$!)H9E~me+E05!%vy5gGsLdi6*)W!;m58aEDTk)(m!Io5 zoMgE0;PO~Xoou&|v8R6Rc%Gh{bx8z<6-*vu$CTr)ChWi*l>1#!{HY|=F4VsU>AJw1 zg%+~vEL83g?Hq=x0Ci9QL+-oR`{%6Jmw6kfHJ-Czh|H!px@?VY6dqr^;dgL#GTi)$ zQ#!D0t4*U{@davt`OY=tD<$Nf78hNlLpGc^`0$_ca_%xk)L2;6yT zPL1o)US5)0mB=l7@Wuv%NX;A#o+=87^(;4+YiX6fe ze2ilozsIIMV^X4Zlak@l@nEK-C<76Rj?;oNmRG-c(9-cST<}7S^{cwMtc%`bzP>Fk z-sB<}W7@lj6M4ALXc9UAgk+@aq)#r)T+mIRl4$LqBYJxeaSpm=(()lvcqpw9%7BWj zu-V}xE=UI*eiX(YD7BW2#!g~Yal)lfI`p5}VgF)y;~z{*wL^eZqQkfA0xaw`Rh4PI7qBspc_gRf+#i*KN6trK~syCT(aID9By@75Hh@W z!%`lmtSxW`_@ZSs_BaYoMbedo@DsAq>;P1C+01dMi*0RFGlj)43%_tL`v=|Hu}2bl zH__Y&1EGy{5KPQ$=27tbSt%sI2VjZj-dOW>{&kw7^jwnE4a#_7Ep+lJC+3ROlSnY= ztq2I$y5h%=IjlP50`6hP^0acO&htye5GvVlD>j8o_LwSaE9Mx+_u?x&0i{9Ghjyi! ze{f}x)}LJYv`}2+jVnWEA&NFu?i1?)x-y14dj(rSW+>}~$M#iza^=1^u3QDEy^wD% zhY$2LFXtL!=x(=tKfiJ1{^p88#O;;&^7{?K&7e%(1)WH76jMw2IO=#7Owhzeh<& zvnYR1!(}t2yaj8-jzGrR{bH1&Z*`euRFUy+L7-@X;4q9t^7AU3Nxh+m zy+;ca7(vTJEp?~Z0jt;q){?T;uzMzT#Pb2K$;s3on0ZgA-EzuX)h$# z;87?0F4dAlqHYdILnqS+N%G-spM=NIlF8lMeek&pO$ov}7|T&BC1~ zCf)}v6u$?+HvwVR$E`l3kmZ$&2iS-wxlKU0;+w~zy{_Y2HiF7i@4ig?du#rSEy*I@ z_4v&#mQy&)kt(-6(J?MtUv4Q3k{pC8+Z1;!a{$#6jMnEFG))YAS~#IaW#+M3r7vWo@p_;pXf20ekdWTp8p7Wpu$%N*(%HSxg*1uO5Kd%)$F_ST)AMGN}&0o0f~7a zq-v)%T$xGW*tabY|WZQ#am>+G>^JAD@cQAY)+0i`iu3?=TlQ zRnE9w7oPo3&sseO%pt>##9Gxo*w&m0#2>Sw4dVf4nq%Sw*Osm1Z|r%Qd6728TL`{0 zowhyd>-k6q_xWRj&K98)Owm}@d7h|0Q>7}iZt~ZznT?2PwofB`&Pr1=flKrw%!BQsYlaf(ergvim?o@rj72oN*nHmW+Zw=srpOy_^zS`qP4X&lX*$4c;u82a9)LP*dFf{lUU?D#pe=mrus`So@ZLhEGx z@w92p^Y!#mXN33WmczYQ+B3SdZsp{tZAR&|;QNwc-Re0IVd|EQhlQv!z@_&7GH=au zr4N!vT}#PuzkGi0wI5aIX(@fWeim9Dc2!ma6^6l(cQZ2!>H5KM!>S~s6E|;R&@xjCLCK_JR8GZYFZj9 zcXn-UZ9RU;#|_18JoKQ6)ZN3pvPqytHP9*d4;JO35v!hcH$iut7cQ#G2Nz{aTo;#R zoQ`2B_j!#VRd@Qr)CeTP^q*PsY7`y=)U7JYYm|)_sg-%L%#R@I;00_VE9NcP3>Rzb zj@oyl;?)_dGn5wfAV33#t&0!XOYFbSFD+3y5CusUQqZ=0Kd0tir3&OwC?f^Mqs#9* za=tu4diqFe4_!?Fj~Gc>wKu33R8*XTHf>g7SEoK|jMXbJolRO!nP%5d<6to)$vHRT zV7-DvK`=@)XH? zcb0IFwP-`%|72!n;oK-%C9>u`$7Mm|-Vk$FzDQ~K^gJL1p>6|jj1eKw1A)$TWC_7k z@%4_FIJ)GMg|@VmR7BMTb<~|4T0CX|dccCSeH-#9h!^x7gN4$Z8e(ZPfs~@!~&e? zY{Pldk>uI72YR=ur_h*B+I>OGv`sBIZ+^(l+&tE_{aIC2Hj=&Y1`en$tju)Ucw;k9 z3K#bWyh3BJY50Nai>A!peTg&}k_rk$XL^_ZxqQN$8ERCK5fKTPL&U^=_9aRHW@e$# zgpnQnYIX&wOnxLx@d7E4?}El-+t7rlx&~gwm6bdWyHW(I=BB2f=0cF~fC|M_!9LmJ zWZ*G`1E5lgIKU{U^%-%1@~H*F;ie_KRnwD;<`2U!0g>+QQ^jmAhdc^rb~-hy&FE^L z9XwTZVV=(}$jCM#?cFI}UYNeqXTa!Tz00L z_n&3lBCB9wVY$^;YfRK?JhA%;e*_gG!l(9+-=>4>oL8vT^sw@Tj4L1cD3I*#7~dp18wYz2`e$XBC3w`Vj{i zvCm8Ii}U@(4wrV}@v@!-T~b_p{9aJtVEmd?s5^W?&=|t5Cz|iuHnp){!VX$-3)YwOEWgBwVTzBYk4M+LcOr8E#UjdM@X65J*Sti>d-M9F68q8`d>}3r+G)_p1gM> zx?*Bt3esCs*Q13(I4gKfTLV|BCON0lN)5j_|;HCV>i&+3YJ;;$c~qG2&$@L=Aa z_H5OG!lOzM7n1Sw;v1QmELQ7vwWD;iEJ{{)v&emT5q!lP@kt3|j~*Pj7c%akV{&lu z-aYv$bVfk})DdaNn1NA8eyFQjM0)*f)y2l;8XO&s=oL8r94xZg;6oSv+2v@Vrh9$j zKsHv;aR16yEf$Rs(h~|lM7ch&8fBxXQjAA{S0?WC&O!cb+vkJ~N2rK(RX{cYV+R%^ zW3JD43Qjx%z>D}~bci8lmo=!^6)y-OJS=eiM+GWOMKlm|L;trOg-jk0+oJCUaiRHd z5zll-$7LN!@*#)B`D6#KLT`3Rrpet~=mMsAV+1EGK|_J@pSiXKiQnNecJa1=)hNNq z=KAG3-W$5`zf^Ujs6}5K^Wv2{5YixUz&3?}JfHW>Dhj-B%bcj2X;X!M>Z8{I53d-d zkBsIvBM#>oZ>3gN`F?O6$8GPRMZ5@TrEmr2A&Yr0dJ9I#A#V^U*{f53jGUciI!x%X_Wxwh<7n&f2(zJZVkRUff;=a0gVa*G-6cOYRxtke)3=o6_uO zoDrT?NQT-Jw_nZNdR1Q9^!BQG0vVk8uyf)ri_E`%Cm@9ivoR8QT8)nSro7|nn0rvH zq%@zXOTn$HO4_XI^sm* zf!NIX!tdyc@O2ebMmic!K|R)%Gb#zokIP{F zw=HRg3|I^2E{(1URZbfy^U%67P#iBPD4WT&+O>4vk%vd@J|H1|-@Wf9`K>(<=in3G zk?>3m5XMwQYbJUacDA-T%>?6@5JE*nk7f--C5Sm_rEsJiIG&_0?q|8d^pz+U$#JcN z)_Q15=gBl~QAkdpK}93J%%Ekp%m-ah%))%Q)7KZ8nwomNIgZEY{M_b6y&`~qw4~s| z`5FY?f##XznchcZT)Box2WPT}+3&N=TBM|V$F&L8bT_Db19jR-o<4}YwlgwoQxS1~ zc^R(Rx}@EaUxDQM6zMzvye%%m@50|-dP4r-59h_t-yd)N424UAf3CODkA{PRu`9v6 zYe`Jfaej;FajS2`PiKOIo>lUiQw!pk3Zj?dj0rszLqj5-XpafPf|8U{>PY+!Cb+6# zvD(gHIF+T0<4h(jaFI9L8EHH@akI=EiYANN&+|qL`ZF>_d^s>RRB-gstH1wu?RqSa zIiI@}TQ@fj?~@wCArvUQ;*JiT>T54OSFAa51WC;B=ySqDI0XNgmo!`g6&IqtJ7~)w z7+6{6L?v-=&WuwSt#wen@zK#yJjTq=B&~v&)@o45ux%T%ivqAPWR#?V<0OzE+BMzbtu9FVX)+4s)QJ|mMtF?B|SP3SprBUnQa zb}DZbFuR-cm1$eD<{Km^XP`_=u;GTbvSb@%ko0`tR)fY;RX8 z{p||DoA&`S5ESs=?AyS`-sq<`=dA!5@LTo5w}1Kn`!6A`TV{&^Dfm>ZO>i5PI+k4= zIXsuuw4u028#;_=ay5cm8a~WwQBhzmvqVsUnikSJGi5Ey#CziDp~50w^^9M$?vrp* z9au!YM4EB;iR#D|fD|}LKDPk^!xGX@d%lR=;eg7F`@8#LS6*-o(omp83;6Q87Qp2@ zw#l%V*d94MD=+dGfi+w5?Qm1yWH;|2F1{Qvm=4H7Yoc1j{5aHUD=%DN347BV&;UP7 z^={qP#kzWBne*W83Y?l+%q!q=DP@VvsMqxQJ2 zAI)*-=9W2`mlMPpJvRr~BnStT+5T7WCLbR7>mNlLLN2#O+RPK5hU4l;iwR?yhi?ea zKw4Mb(V?8tkfr%!bhz?u@H06jVp`CFZQ5C(O6e}`lXfx9>}sg!%5uwxpLB%?0H(R7 z>ys44fixu$paa9bN4I01%oWNWfO${#)b~kmyl0R%oqI@~63;0aS*We2W zDTx#{^ipXnwBgCxJHwr2O4v`&MdnZ6Qu4p2w7)H6Ps>}rF21ES(mzvL&(`+;GWyrI zI9+kX`prnP4RfCts%^PG{v8DzfZrl-Fh?Xp7phiGY<8|ur)}s>=p8>`5tiZyUPYnLD^hbR zwHgp~=`;+#9MlxnMlyNVh z7C>A{FYn!L!#0^s>{&f0i=Vp&`jW0(H}jBv<+kF%BDxnanbdH`M%2?H6z5Jd0r0~5 z%h<1VDmAxd(C;6PU!|jZdd6R1{%gL+;CgggzU8~kTfV=Qp#8^BxRZmUjn)69{I8U6 zieJb;3gAvNCS!@VR)( zBzMD&S~ases)-4#gHq!LgByj>L1~Qal4NBH>58E;G174eCbsQDiP(H>wWV|o2qIF$ z(eNLFI!Z7HfikM;WlrYiHg;FA<98^KtO;r>74t*YsYhc1w+j5IR&48qYhNFakiOAhJ$uS0uhkG+(diW3Dln`q_Jp@Uv-X40lZtlTW%g zNFE2>a@Qx0*{S)mosa6#gtb>@jN{XNcZ^G)yP&o>B43jXg+PetaG9$EDE62LFXfu5zp8j4$1_q%8 z`kyK#|N2b+Jo}fr$#Rna3Gkm)TK@^q_m=s8T1EaLqy9bc_d=AvLUAGgGTHs7ZRzjv zzgx2ZikE-$h5ECsV19je|Jst@Hv{~F zz?b?@h+o6=Yiq#o4f}}A complex named data element consisting of an optional set of [*flags*](#flag) and an optional sequence of model instances.{{}} + +An assembly does not have an associated value. + +An assembly may reference or directly define zero or more [*flags*](#flag). Flag instances associated with an assembly definition typically provide additional metadata used to identify or characterize the object represented by the assembly. + +An assembly has an optional model consisting of references to zero or more [*assemblies*](#assembly) or [*fields*](#field) as model instances. These model instances allow complex data to be composed within an assembly. + +An *assembly definition* is a type of [*definition*](#definition) within a given [*Metaschema module*](#metaschema-module) used to represent the implementation of a complex [*information element*](#information-element) as an assembly. + +## Data Model + +A *data model*, abbreviated as DM, is defined as follows: + +{{}}A representation of an [*information model*](#information-model) in a format specific serializable form (e.g., XML, JSON, YAML) expressed using a format-specific schema syntax.{{}} + +> As described by [RFC 3444](https://tools.ietf.org/html/rfc3444#section-4)), a data model is defined at a lower level of abstraction than the information model it represents, and includes many details. +> +> - Intended for implementors +> - Include protocol-specific constructs. + +In Metaschema, the format-specific schema (i.e., XML or JSON Schema) is generated within the Metaschema architecture from a [*Metaschema module*](#metaschema-module). By defining *data models* appropriate and tuned for each format, these generated schemas can be used to validate that data is conformant to the associated format, and thus conformant to the *information model* defined by a given *Metaschema module*. + +## Definition + +{{}}A distinct [*information element*](#information-element) implementation within a [*Metaschema module*](#metaschema-module) representing a semantically well-defined data structure, along with any associated data type(s), information element relationships, cardinalities, and other information characteristics.{{}} + +An [*assembly*](#assembly) definition, [*field*](#field) definition, or [*flag*](#flag) definition are types of *definitions* within a *Metaschema module*. + +## Domain + +An information *domain* is defined as follows: + +{{}}A specific area of knowledge, interest, and/or practice.{{}} + +## Flag + +A *flag* is defined as follows: + +{{}}A simple named data element with an associated primitive value.{{}} + +A *flag* is a pairing of a name and a value. + +A flag typically provides identifying or classifying information for the containing [*assembly*](#assembly) or [*field*](#field). + +The flag's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types). + +A *flag definition* is a type of [*definition*](#definition) within a given [*Metaschema module*](#metaschema-module) used to represent the implementation of a simple, named [*information element*](#information-element) with an associated primitive value as a flag. + +## Field + +A *field* is defined as follows: + +{{}}A complex named data element consisting of a required value and an optional set of [*flags*](#flag).{{}} + +A field is typically used to provide supporting information for a containing [*assembly*](#assembly). + +The field's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) or [markup data types](/specification/datatypes/#markup-data-types). + +A *field definition* is a type of [*definition*](#definition) within a given [*Metaschema module*](#metaschema-module) used to represent the implementation of a named complex [*information element*](#information-element) with an associated primitive or markup typed value, and zero or more [*flags*](#flag) as a field. + +## Information Element + +An *information element* is defined as follows: + +{{}}A given data concept within a specific [*domain*](#domain) representing a semantically well-defined data structure, along with their data type(s), cardinalities, and other information characteristics. A part of a larger [*information model*](#information-model).{{}} + +An *information element* is implemented by a [*definition*](#definition) in a [*Metaschema module*](#metaschema-module). + +## Information Model + +An *information model*, abbreviated as IM, is defined as follows: + +{{}}A format-neutral description of a set of [*information elements*](#information-element) for a given [*domain*](#domain).{{}} + +> As described by [RFC 3444](https://tools.ietf.org/html/rfc3444#section-3)), an IM describes *information elements* at a conceptual level, independent of any specific implementations or protocols used to transport the data. +> +> - Level of abstraction depends on the modeling needs of the designers +> - Define relationships between managed objects +> - Should hide all protocol or implementation details, allowing for different implementations + +## Metaschema Module + +A *Metaschema module* is defined as follows: + +{{}}A format for describing the implementation of each [*information element*](#information-element) contained within an [*information model*](#information-model) using Metaschema syntax. Each *information element* is implemented by a [*definition*](#definition) which provides details about the information element's structure, meaning (semantics) and use.{{}} + +A Metaschema module is composed of flag, field, and assembly definitions. + +- **[Flag](#flag):** A simple named data object with an associated scalar value. A simple name / value pair. A flag is used to represent a leaf information element. +- **[Field](#field):** A complex named data object with an associated scalar or markup typed value and zero or more flags. A field is used to represent an edge information element. +- **[Assembly](#assembly):** A complex named data object, with no value, zero or more flags, and a complex model consisting of a combination of child fields and assemblies. An assembly is used to represent a composite information element. + +A Metaschema module can be used as the basis for producing schema files, content conversion utilities, documentation, parsing code, and other artifacts that can be used in support of handling data aligned with an information model. diff --git a/website/content/specification/im-model.svg b/website/content/specification/im-model.svg new file mode 100644 index 000000000..0c6ab5bef --- /dev/null +++ b/website/content/specification/im-model.svg @@ -0,0 +1,136 @@ + + + + + + + + + + + + + + + + Page-1 + + Dynamic connector.24 + + + + Sheet.1 + Information Model + + Information Model + + Sheet.7 + Metaschema Module + + Metaschema Module + + Sheet.10 + Definitions + + Definitions + + Dynamic connector.18 + + + + Sheet.33 + Assembly Definition + + Assembly Definition + + Rectangle + Assembly Model + + Assembly Model + + Sheet.30 + Choice + + Choice + + Sheet.11 + Flag Definition + + Flag Definition + + Sheet.37 + Value + + Value + + Dynamic connector.19 + + + + Sheet.12 + Field Definition + + Field Definition + + Sheet.38 + Flag Instance + + Flag Instance + + Sheet.39 + Value + + Value + + Sheet.16 + Field Instance + + Field Instance + + Dynamic connector.21 + + + + Sheet.31 + Flag Instance + + Flag Instance + + Dynamic connector.20 + + + + Sheet.17 + Assembly Instance + + Assembly Instance + + Dynamic connector.23 + + + + Sheet.3 + Information Elements + + Information Elements + + diff --git a/website/content/specification/im-model.vsdx b/website/content/specification/im-model.vsdx new file mode 100644 index 0000000000000000000000000000000000000000..769006cf4154f4a701626572494893fdc344b80f GIT binary patch literal 27790 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 --> b((b)) + b -- e2 --> c((c)) + a -- e3 --> c +``` + +A *Metaschema module* is a *directed graph*, since the *edges* represent a set of ordered node pairs. This allows a *Metaschema module* to represent sequences of relationships. In the example above, `a` has two ordered relationships: a -e1-> b and a -e3-> c. + +A *Metaschema module* is a *multigraph*, since two *nodes* may have multiple edges representing distinct relationships between the two nodes. This allows a *Metaschema module* to represent different relationships between the same two information elements, such as the relationships e3 and e4 between `a` and `c` below. + +```mermaid +graph TB + a((a)) -- e1 --> b((b)) + b -- e2 --> c((c)) + a -- e3 --> c + a -- e4 --> c +``` + +A *Metaschema module* is a *cyclic graph*, since a sequence of *nodes* and *edges* can form a circuit where the first and last *nodes* are the same. This allows a *Metaschema module* to represent recursive information structures. This is illustrated below where a -e1-> b -e2-> c -e3-> a form a cycle with node `a` is the first and last node in the cycle. + +```mermaid +graph TB + a((a)) -- e1 --> b((b)) + b -- e2 --> c((c)) + c -- e3 --> a +``` + +In a *Metaschema module* a node is represented as a [*definition*](/specification/glossary/#definition). Each *definition* represents a given *information element* in an *information model*. Each *definition* contains data and documentation about the meaning (semantics), structure (syntax), and use of a given *information element*. + +In a *Metaschema module* an *edge* is represented as an [*instance*](/specification/syntax/instances/), which establishes a relationship between two *information elements* in an *information model*. Each *instance* contains data and documentation about the relationship, including data about the cardinality, meaning (semantics), structure (syntax), and use of the relationship. + +While a *Metaschema module* represents a cyclic directed multigraph, there are a few assumptions that ensure that data representations based on the information model conform to an oriented acyclic directed multigraph. This is necessary to support JSON and XML data representations which use a tree form. + +- At least one root node MUST be defined in the *information model*. A root node ensures that orientation is supported, providing a root of the data tree. Multiple root nodes are also possible allowing multiple resulting oriented acyclic directed multigraphs to be produced. +- Nodes involved in a cycle MUST allow for cycle termination. This can be achieved by a zero minimum cardinality on an edge creating a cycle. + +## Object-Oriented Basis of Metaschema + +In a *Metaschema module*, the cyclic directed multigraph representing an *information model* is represented as a hierarchy using a *compositional* approach to describe *information elements*. This approach aligns well with the hierarchical form of JSON, YAML, and XML; and also supports programming language data structures that are based on object-oriented principles. + +In object-oriented programming languages, a *class* can be used to represent an *information element*. An *object* represents a data instance of a *class*, which can also be considered an instantiation of an *information element*. Each composite *member* of a *class* can be used to represent a relationship to an *object* of another class. Thus, a *class member* represents a specific type of relationship between two *information elements*. This compositional form is often referred to as a `has-a` relationship. + +For example: + +```mermaid +classDiagram + class Computer { + -id : string + } + class ComputerPart { + -id : string + } + Computer "1" --o "*" ComputerPart : consistsOf + ComputerPart "0" --o "*" ComputerPart : consistsOf + Computer "1" --o "*" ComputerPart : usbConnectionTo +``` + +In this example the `Computer` class establishes an aggregate compositional relationship `consistsOf` to a `ComputerPart` class. This is a way of stating that a computer is made up of a set of parts. + +In a *Metaschema module*, the *information element* concepts of a `Computer` and a `ComputerPart` can be represented as a *definition*. Thus, a *definition* represents a *class*. The `consistsOf` relationship is represented as an *instance*. Thus, an *instance* represents a *class member*. + +The following illustrates how the object-oriented approach used to describe a computer can be represented as a cyclic directed multigraph. + +```mermaid +graph TB + computer -- identifiedBy --> computer-id[id] + computer-part[ComputerPart] -- identifiedBy --> computer-part-id[id] + computer -- consistsOf --> computer-part + computer-part -- consistsOf --> computer-part + computer -- usbConnectionTo --> computer-part +``` + +The duality of the *Metaschema module* as both a representation of a cyclic directed multigraph and a set of object-oriented classes is explored in this specification. + +# Definitions, Instances, and Local Definitions + +Metaschema uses 3 types of [*definitions*](/specification/syntax/definitions/) to represent information elements with different structural shapes: [`define-flag`](/specification/syntax/definitions/#top-level-define-flag), [`define-field`](/specification/syntax/definitions/#top-level-define-field), and [`define-assembly`](/specification/syntax/definitions/#top-level-define-assembly). These *definition* types are used as building blocks of a Metaschema-based model. + +*Field definitions* and *assembly definitions* allow the identification of edges through the declaration of an [*instance*](/specification/syntax/instances/). An *instance* represents an edge between the containing definition and another definition. Thus, an *instance* makes use of another definition, typically by reference. + +Both field and assembly definitions optionally allow the inclusion of one or more child [*flag instances*](/specification/syntax/instances/#flag-instance). + +An assembly definition also has a [complex model](/specification/syntax/definitions/#model) which contains a sequence of [*model instances*](/specification/syntax/instances/#model-instances), each *model instance* is either a [*field instance*](/specification/syntax/instances/#field-instance) or an [*assembly instance*](/specification/syntax/instances/#assembly-instance). + +{{}} +Within a *Metaschema module*, the *information model* implementation consists of assemblies, each of which are composed of more assembly, field, and flag instances. + +*Field instances* and *assembly instances* support the composition of complex *information elements*. + +Flag instances may exist on fields and assemblies, providing identifying or qualifying data about their containing definition. + +The following example illustrates the use of each type of *definition*, and the use of *flag instances* and *model instances* to create a more complex model through composition. + +```mermaid +graph TD + subgraph asmb-def-1[Assembly Definition: asmb-def-1] + flg-inst-1[Flag Instance: flg-inst-1] + asmb-def-1-model + end + subgraph asmb-def-1-model[Model] + fld-inst-1[Field Instance: fld-inst-1] + asmb-inst-1[Assembly Instance: asmb-inst-1] + end + subgraph fld-def-1[Field Definition: fld-def-1] + flg-inst-2[Flag Instance: flg-inst-2] + end + flg-def-1[Flag Definition: flg-def-1] + asmb-def-2[Assembly Definition asmb-def-2] + fld-inst-1-->fld-def-1 + flg-inst-1-->flg-def-1 + flg-inst-2-->flg-def-1 + asmb-inst-1-->asmb-def-2 + +classDef definition fill:#dfe1e2,stroke:grey,stroke-width:4px,stroke-opacity:0.2 +classDef model fill:#f0f0f0,stroke:grey,stroke-width:4px,stroke-opacity:0.2 +classDef instance fill:#d9e8f6,stroke:grey,stroke-width:4px,stroke-opacity:0.2 + +class asmb-def-1,asmb-def-2,fld-def-1,flg-def-1 definition +class asmb-def-1-model model +class flg-inst-1,flg-inst-2,fld-inst-1,asmb-inst-1 instance +``` + +The example above declares 4 distinct object definitions, along with their instances. + +- The *flag definition* `flg-def-1` represents a reusable [*flag*](/specification/glossary/#flag). +- The *field definition* `fld-def-1` represents a reusable [*field*](/specification/glossary/#field). +- The *assembly definitions* `asmb-def-1` and `asmb-def-2` represent reusable [*assemblies*](/specification/glossary/#assembly). + +Through the compositional use of *flag instances* and *model instances*, it is possible to build a complex *information element* by declaring how smaller *information elements* are combined together through composition. + +![Composition Example](../def-inst.svg) + +In the example above, the *assembly definition* `asmb-def-1` and the *field definition* `fld-def-1` both instantiate the flag defined as `flg-def-1`. These *instances*, `flg-inst-1` and `flg-inst-2` respectively, are examples of *flag instances*. The *assembly definition* `asmb-def-1` declares the *flag instance* `flg-inst-1` as a composite child by referencing the *flag definition* `flg-def-1`. Similarly, the *field definition* `fld-def-1` declares the *flag instance* `flg-inst-2` as a composite child by referencing the *flag definition* `flg-def-1`. + +Furthermore, the *assembly definition* `asmb-def-1` has a complex model that instantiates the *assembly definition* `asmb-def-2`, as `asmb-inst-1`, and the *field definition* `fld-def-1`, as `fld-inst-1`. These are examples of *model instances*. +{{}} + +*Assemblies* and *fields* also allow *inline definitions* to be declared which represent a single use *definition* that is also an *instance*. In these cases the inline ``, ``, and `` elements are used, which combine the data elements used to declare a *definition* and *instance* of the same type. diff --git a/website/content/specification/mapping.md b/website/content/specification/mapping.md new file mode 100644 index 000000000..1a765821e --- /dev/null +++ b/website/content/specification/mapping.md @@ -0,0 +1,91 @@ +--- +title: "Binding to XML, JSON, and YAML" +linkTitle: Format Bindings +description: "Discussion of how Metaschema primitives map to XML, JSON, and YAML primitives" +weight: 50 +aliases: +- /specification/mapping/ +--- + +# Binding to XML, JSON, and YAML + +**Note: This section of the specification is still a work in progress.** + +XML, JSON, and YAML each use specialized terminology and format primitives. As a notation for an object-based data, YAML is fairly similar to JSON, while XML is quite different to the other two. While all data format describe tree structures (directed graphs), each format (with its implicit data model) has its particular design, which requires specification in detail. + +For example, a data point represented as an attribute on an element in XML, for example, might be a string property on a data object in JSON. The metaschema moderates this distinction by providing rules regarding its own semantic constructs and how they are to be represented in the target format. As a result, a mapping between JSON and XML concepts is implicitly available through the corresponding metaschema. + +Within Metaschema-based models, all constructs are optional unless marked otherwise. + +| Metaschema | XML | JSON and YAML | +|------------------|-----|------| +| Assembly | An element with element content | An object, either a property or a member of an array property | +| Field (with no flags) | A single element with text content | String property | +| Field with one or more flags | An element with text content, flags as attributes | An object property with a designated property for its nominal string value as well as properties for its flags | +| Flag | Attribute | String property | +| Flag with designated data type | Attribute with lexical constraints per type | String property with lexical constraints per type, or typed property such as `number` or URI (per type) | +| Field `as-type='simple-markup'`, no flags permitted | An element permitting mixed content inline | String property or map with string property, parsable as markdown (line only) | +| Field `as='complex-markup'`, flag(s) permitted | An element permitting mixed content inline | Object property with `RICHTEXT` String property or object with string property, parsable as markdown (full blocks) | + + +## XML Representational Form + +### Flag Instance + +In XML, a flag instance is represented as an [attribute](https://www.w3.org/TR/xml/#attdecls). + +```xml + +``` + +### Field Instance + + +In XML, a field is represented in two possible ways: + +1. As an XML element. + + The representational form of a field varies based on the presence of child flags. + + ```xml + field value + ``` + + or + + ```xml + field value + ``` + + The form immediately above is used when the field has a child flag instance. + +1. As a text value in an unwrapped form. + + ```xml + field value + ``` + + This form is only allowed when a field has no child flags. + +## JSON Representational Form + +### Flag Instance + +In JSON a flag instance is represented as an [object member](https://datatracker.ietf.org/doc/html/rfc8259#section-2) with an associated value. + +```json +{ + "flag-name": "flag value" +} +``` + +## YAML Representational Form + +### Flag Instance + +The YAML representation is similar to JSON, where a [tagged value](https://yaml.org/spec/1.2.2/#24-tags) is used to represent a flag. + +```yaml +flag-name: flag value +``` + diff --git a/website/content/specification/mapping/_index.md b/website/content/specification/mapping/_index.md deleted file mode 100644 index afbd4f177..000000000 --- a/website/content/specification/mapping/_index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "Mapping to XML, JSON, and YAML" -Description: "Discussion of how Metaschema primatives map to XML, JSON, and YAML primatives" -weight: 90 ---- - -XML, JSON, and YAML each use specialized terminology and format primatives. As a notation for an object-based data, YAML is fairly similar to JSON, while XML is quite different to the other two. While all data format describe tree structures (directed graphs), each format (with its implicit data model) has its peculiar design, which requires specification in detail. - -For example, a data point represented as an attribute on an element in XML, for example, might be a string property on a data object in JSON. The metaschema moderates this distinction by providing rules regarding its own semantic constructs and how they are to be represented in the target format. As a result, a mapping between JSON and XML concepts is implicitly available through the corresponding metaschema. - -Within OSCAL models, all constructs are optional unless marked otherwise. - -| OSCAL Metaschema | XML | JSON and YAML | -|------------------|-----|------| -| Assembly | An element with element content | An object, either a property or a member of an array property | -| Field (with no flags) | A single element with text content | String property | -| Field with one or more flags | An element with text content, flags as attributes | An object property with a designated property for its nominal string value as well as properties for its flags | -| Flag | Attribute | String property | -| Flag with designated data type | Attribute with lexical constraints per type | String property with lexical constraints per type, or typed property such as `number` or URI (per type) | -| Field `as-type='simple-markup'`, no flags permitted | An element permitting mixed content inline | String property or map with string property, parseable as markdown (line only) | -| Field `as='complex-markup'`, flag(s) permitted | An element permitting mixed content inline | Object property with `RICHTEXT` String property or object with string property, parseable as markdown (full blocks) | - diff --git a/website/content/specification/concepts/metaschema-information-elements.png b/website/content/specification/metaschema-information-elements.png similarity index 100% rename from website/content/specification/concepts/metaschema-information-elements.png rename to website/content/specification/metaschema-information-elements.png diff --git a/website/content/specification/overview.md b/website/content/specification/overview.md new file mode 100644 index 000000000..208e21680 --- /dev/null +++ b/website/content/specification/overview.md @@ -0,0 +1,60 @@ +--- +title: "Overview" +description: "Discusses the information modeling concepts used by Metaschema." +weight: 10 +--- + +# Overview + +The *Metaschema Information Modeling Framework* provides a means to represent an [*information model*](/specification/glossary/#information-model) for a given [*information domain*](/specification/glossary/#domain), consisting of many related [*information elements*](/specification/glossary/#information-element), in a *data format* neutral form. By abstracting information modeling away from *data format* specific forms, the Metaschema Information Modeling Framework provides a means to consistently and sustainably maintain an *information model*, while avoiding the need to maintain each derivative *data format* individually. By consolidating *information model* maintenance into a single representation, significant time can be saved over other approaches that require each *data format* to be maintained individually. + +A Metaschema-based *information model* is represented in an abstract XML-based format, called a [*Metaschema module*](/specification/glossary/#metaschema-module). A *Metaschema module* represents implementations of the individual *information elements* of the *information model* using [*definitions*](/specification/glossary/#definition). These *definitions* are bound tightly to representational forms in each supported derivative *data format*, unifying representations for a given information model. Based on the tight binding provided by the Metaschema Information Modeling Framework, a given *information model* can be used to deterministically generate a [*data model*](/specification/glossary/#data-model) in a *data format* specific form. + +The Metaschema framework currently supports XML, JSON, and YAML *data formats*. Support for YAML is limited to the subset of YAML that aligns with JSON representations. + +This tight binding to supported derivative data formats has many advantages. + +1. **Automated Schema Generation:** Schema representations for a given supported *data format* can be automatically generated from a Metaschema module. A generated schema can be used to validate that data is conformant to the associated *data model*, ensuring that this data is conformant to the *information model* defined by the *Metaschema module*. When the *information model* is changed, an updated schema representation can be automatically generated. +1. **Automated Translation of Content:** Data represented using a *data model* derived from a *Metaschema module* can be automatically translated into an alternate *data model* based on the same *Metaschema module*. This allows data aligned with a derived *data model* to be automatically converted into data representations in all other *data models* derived from the same *Metaschema module*. +1. **Automated Documentation Generation:** *Data model* specific documentation can be automatically generated from a *Metaschema module*. This generated documentation is oriented to the syntax and concepts of the *data format* used by the *data model*, providing a format-specific view of an *information model*. +1. **Automated Parsing Code Generation:** Programming language specific parsing and content generation code can also be automatically generated using a *Metaschema module*, supporting data deserialization and serialization for all derived *data models*. The data structures generated represent the *information model* allowing data read from and written to all derived *data models* to be represented in a singular set of data structures. This generative approach allows application developers to focus right away on business logic and user interface features, instead of building the data structures needed to represent the *data models* for a given *information domain*. + +The following illustrates the Metaschema Framework architecture as described above. + +```mermaid +graph TB + ms[Metaschema module] -- generate --> schema[XML and JSON Schema] + ms -- generate --> doc[HTML-based Documentation] + ms -- generate --> code[Parsing Code] + ms -- support --> conv[Conversion between formats] + classDef metasch fill:#dfe1e2,stroke:grey,stroke-width:4px,stroke-opacity:0.2 + classDef usecase fill:#f0f0f0,stroke:grey,stroke-width:4px,stroke-opacity:0.2 + class ms metasch + class code,schema,doc,conv usecase +``` + +These capabilities can be applied to any *information domain*, serving developers who need to support multiple *data models* for a given *information domain* or a format specific technology stack that is well-suited to their application based on a single *data model* equally. In either case, use of the generative capabilities supported by the Metaschema Information Modeling Framework, further reduces the time required to maintain format-specific documentation, schemas, data, and parsing code in one or multiple *data formats*. + +This specification provides a basis for the development of interoperable toolchains supporting the generative capabilities of the Metaschema Framework. This specification is also intended to serve as a reference for information modelers producing Metaschema-based *information models*. + +## Design Goals + +The design of the Metaschema modeling approach addresses the following needs: + +1. **Ease Maintenance:** Reduce the implementation burden of supporting multiple *data formats* for a single *information model*, along with documentation, schemas, data, and related tooling. +1. **Ease Format Adoption Costs:** Reduce the cost of adopting a new supported *data format* for use with a given *information model*. As bindings to new *data formats* are supported by the Metaschema Modeling Framework, users of supporting tools gain use of the new *data format*. +1. **Unified Format Support:** Unify support for compatible data descriptions in multiple *data formats*, such as XML, JSON, YAML and potentially others over time. For a given *information model* data can be easily translated between *data models* in all supported *data formats*. +1. **Ease Production of Data Format Documentation:** Produce *data model* documentation from the same source as schema files and associated tools. +1. **Promote Information Model Experimentation:** Enable distributed, semi-coordinated experimentation around information concepts within a given *information domain*. *Information elements* can be easily added, modified, and removed. Documentation, schemas, and tools can be quickly updated using automated generative tools supported by a given *Metaschema module*. + +## Design Approach + +The Metaschema Modeling Framework provides a reduced, lightweight modeling language with constraints that apply at the level of the information model abstraction. + +The following philosophy was used in the current design: + +- **Mediate Formats' Structural Differences:** Mediate between the structural differences in the XML, JSON, and YAML *data formats* by providing format-specific tailoring capabilities that improve the expression and conciseness of Metaschema-based data in a given format. This has the added benefit of making Metaschema easier to learn and use over learning the idiosyncrasies of each *data format*. +- **Capitalize on Format Features:** To the extent possible, maximize the use of *data format*-specific features, while still aligning modeling functionality across all supported *data formats*. In some cases, support for specific *data format* and schema features may be omitted where these features do not align well across all supported *data formats*. +- **Unify Information Modeling Across Formats:** Use modeling constructs that map cleanly into features offered by XML and JSON schema technologies. This ensures that all information can be preserved, without data loss in bidirectional conversion. +- **Reduce Runtime Complexities:** Eliminate the need for additional inputs, reliance on arbitrary conventions, or runtime settings to reliably produce correspondent XML, JSON or YAML from any other supported *data format*. +- **Focus on Running Code:** Focus on the production of a rich specification that facilitates running code supporting automated generation of schemas, documentation, tooling, and other model-related artifacts consistent with the *information model* defined and documented by a given *Metaschema module*. diff --git a/website/content/specification/syntax/_index.md b/website/content/specification/syntax/_index.md index bb204acad..aa0dc31c3 100644 --- a/website/content/specification/syntax/_index.md +++ b/website/content/specification/syntax/_index.md @@ -1,280 +1,353 @@ --- title: "Metaschema Syntax" -description: "Overview of the Metaschema syntax" -weight: 50 -sidenav: - toc: - includeHtml: true - headingselectors: h2,h3,h4,h5 +linkTitle: "Syntax" +description: "Discusses the Metaschema module format and related structures." +weight: 30 +aliases: +- /specification/syntax/ +custom_css: +- /css/element-map.css --- -A Metaschema instance has two parts: a header (the `METASCHEMA` element), and a set of definitions for the model components or parts supported by the `define-assembly`, `define-field`, and `define-flag` elements. - -Top level documentation for the Metaschema instance appears in the header section, while documentation for all the model components appears with the definitions for those constructs. There is no explicit separation between the header and the definitions: the header ends when the definitions start. - -## Root Element -### `METASCHEMA` element - -The root element is `METASCHEMA` using all capitals. To name the root element in all capitals (unlike the general rule) and to give it a name somewhat peculiar to its application, retains and expresses the information that it is intended to be the document root. This is the only element named in all caps. - -Attributes: - -- `@root`: indicates the root element or object for the schema, which must correspond to the `@name` of one of the (assembly) definitions in the metaschema. - -A metaschema definition may include these elements, in order: - -#### `schema-name` - -Describing the scope of application of the data format, for example "OSCAL Catalog". - -#### `schema-version` - -A literal value indicating the version to be assigned to schemas and tools produced from the Metaschema. - -#### `short-name` - -A coded version of the schema name, for use when a string-safe identifier is needed, for example on artifact file names. Expect this short name to be propagated anytime such a "handle" is needed. A short name for the OSCAL Catalog metaschema (and schemas) might be `oscal-catalog`. - -#### `namespace` - -An XML namespace identifier (URI) to be used for the resulting XSD. All elements in the metaschema will be assigned to this namespace, including elements defined in metaschema modules, that are designated with their own namespaces. (In other words, this data value is operative only for the top-level metaschema, not for any of its imported modules. This makes it possible to use modules in metaschemas defined with different namespaces.) - -#### `remarks` - -Paragraphs describing the metaschema. - -Note that the `remarks` element is also permitted to appear elsewhere; this is a general-purpose element for including explanatory commentary of any kind; its scope of application is generally shown by its location in the document - the top-level remarks should describe the entire metaschema. - -#### `import` - -Used to import the components defined in another metaschema definition into this metaschema definition. - -#### Component Definitions - -Following the `METASCHEMA/remarks`, any number of schema component definitions may follow. These describe each component, provide information determining details of its representation and handling (in XML and JSON), and include documentation. - -Each component is defined by one of the `define-assembly`, `define-field`, and `define-flag` child elements, which are described individually below. - -## Component Definitions - -The `define-assembly`, `define-field`, and `define-flag` child elements have a common base model. - -### Common Elements - -#### `formal-name` - -A label for use in documentation to provide a human-readable name for the component. The `formal-name` element is required. - -#### `description` - -A semantic definition for the component for use in documentation. This definition ties the component to the related concept in the information domain the model is representing. The `description` element is required. - -#### `remarks` - -Provides notes on the use of the component that may clarify the semantic definition for the component for use in documentation. The `remarks` element is optional and may occur multiple times. - -#### `example` - -Used to provide inline use examples in XML, which can then be automatically converted into other formats. The `example` element is optional and may occur multiple times. - -### `define-field` - -Fields can be thought of as simple text values, either scalars or sequences of scalars, or when appropriate, of "rich text" or mixed content, i.e. text permitting inline formatting. Depending on modeling requirements, fields may also be used for even simpler bits of data, such as objects that carry specialized flags but have no values or structures otherwise. This means that fields can be more or less complex, depending on the need. - -Attributes: - -- `@as-type`(type: string, use: optional, default: string): Defines the type of the field's value. The `@as-type` attribute must have a value that corresponds to a [data type](#data-types). -- `@collapsible`(type: yes/no, use: optional, default: yes): Is a JSON and YAML specific behavior that allows multiple fields having the same set of flag values to be collapsed into a single object with a value property that is an array of values. This makes JSON and YAML formatted data more concise. -- `@name`(type: NCName, use: required): Used to identify the field when it is referenced within the metaschema definition. - -The following elements are supported: - -#### `json-key` - -See [using `@json-key`](#using-json-key). - -#### `json-value-key` - -In XML, the value of a field appears as the child of the field's element. In JSON and YAML, a property name is needed for the value. The `json-value-key` element provides the property name in one of three possible ways: - -1. A value is provided that is used as the property name. -2. A `@flag-name` value is provided that indicates the flag's value to use as the property name. This results in a property that is a combination of the referenced flag's value and the field's value. For example: "flag-value": "field-value". -3. If the `json-value-key` is not specified, a default value will be chosen based on the data type as follows: - - If the data type is `empty` no property will exist, so no property name is needed. - - If the data type is `markup-line`, then the property name will be `RICHTEXT`. - - If the data type is `markup-multiline`, then the property name will be `prose`. - - Otherwise, the property name will be `STRVALUE`. - -#### `flag` - -See [local defintion of `flag` components](#local-defintion-of-flag-components). - -In addition to these settings, fields may be defined with flags. Do this by including `flag` elements directly in the definition. - -#### `allowed-values` - -See [using `allowed-values`](#using-allowed-values). - -### `define-assembly` - -An assembly is similar to a field, except it contains structured content (objects or elements), not text or unstructured "rich text". The contents permitted in a particular (type of) assembly are indicated in its `model` element. - -An `@as-type` attribute is not permitted on an assembly definition. - -#### `json-key` - -See [using `@json-key`](#using-json-key). - -#### `flag` - -See [local defintion of `flag` components](#local-defintion-of-flag-components). - -#### `model` - -This element is used to reference the `field` and `assembly` components that compose the assembly's model. A `choice` element is also provided to define mutually exclusive model members. - -##### Redefining the `description` - -The optional `description` element of the child `field` and `assembly` elements can be used to provide a different description for when the referenced component is used in the specified model context. - -##### Using cardinalities and `group-as` - -The child `field` and `assembly` elements share the following common set of attributes: - -- `@ref`(type: NCName, use: required): References the name of the corresponding `define-field` or `define-assembly`. -- `@min-occurs` (type: nonNegativeInteger, use: optional, default: 0): Indicates the minimum allowed occurance of the corresponding `define-field` or `define-assembly`. -- `@max-occurs` (type: positiveInteger or "unbounded", use: optional, default: 1): Indicates the maximum allowed occurance of the corresponding `define-field` or `define-assembly`. The value `unbounded` indicates the the referenced component can occur any number of times. - -The `group-as` element is required if the `@max-occurs` attribute has a value greater than '1' or `unbounded` to provide additional information about how to handle the collection of data. - -The `group-as` element has the following set of attributes: - -- `@name`(type: NCName, use: required): The grouping name to use in XML, JSON, and YAML. Use of this name is further clarified by the `@in-xml` attribute, when used. -- `@in-json` (type: special, use: optional, default: SINGLETON_OR_ARRAY): - - In all cases, `@name` value is used as the property name. - - | Value | JSON Behavior | - |:--- |:--- | - | ARRAY | The child objects are to be represented as an array of objects. | - | SINGLETON_OR_ARRAY | If a single object is provided, then the child will be an object, otherwise the child objects will be represented as an array of objects. | - | BY_KEY | An itermediate object will be used as the child, with property names equal to the value of the referenced `define-field` or `define-assembly` component's flag as specified by the `@json-key` attribute on that component. See [using `@json-key`](#using-json-key). | - -- `@in-xml` (type: special, use: optional, default: UNGROUPED): - - | Value | JSON Behavior | - |:--- |:--- | - | GROUPED | The child elements will be placed within a wrapper element with a localname equal to the value of the `@name` attribute. Each child element's localname will be the `@name` of the referenced component. | - | UNGROUPED | The `@name` attribute is ignored. Each child element's localname will be the `@name` of the referenced component. | - -##### `assembly` - -Used to reference an `assembly-definition` who's `@name` matches the value of the `@ref` attribute. - -##### `field` - -Used to reference a `field-definition` who's `@name` matches the value of the `@ref` attribute. - -- `@in-xml` - -See [using `allowed-values`](#using-allowed-values). - -### `define-flag` - -While data of arbitrary complexity is represented by assemblies (which may contain assemblies), at the other extreme, flags are available for the most granular bits of qualifying information. Since data already appears as text values of fields, flags might not be necessary. But they are extremely useful both for enabling more economical expression of data and especially process-oriented or "semantic" metadata such as controlled values, formal or informal taxonomic classifications etc. etc. - -Attributes: - -- `@as-type`(type: string, use: optional, default: string): Defines the type of the flag's value. The `@as-type` attribute must have a value that corresponds to a [simple](#simple-data-types) (excluding "empty") or [formatted string](#formatted-string-data-types) data type. -- `@name`(type: NCName, use: required): Used to identify the flag when it is referenced within the metaschema definition. - -#### `allowed-values` - -See [using `allowed-values`](#using-allowed-values). - -## Local Refinements - -### Local defintion of `flag` components - -TBD - -### Using `@json-key` - -TBD - -### Using `allowed-values` - -TBD - -## Data types - -A data type can be specified in a metaschema definition within a `define-field`, `field`, `define-flag`, or `flag` component definition using the `@as-type` attribute. The following are the allowed data types. - -## Enumerated values - -Additionally, flags may be constrained to a set of known values listed in advance. - -This restriction can be either: - -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: - -```xml - - Hash algorithm - Method by which a hash is derived - - - Documentation for one permissible option. - Documentation for another permissible option. - - ... -``` -## Metaschema modeling - -In the case of field and flag objects, the modeling constraints to be imposed by the result schemas (either XSD or JSON Schema) over the data set, can be determined on the basis of how they are described. Assembly definitions, however, permit not only flags to be assigned to assemblies of the defined type; additionally, they contain a `model` element for a *mode declaration*. This declaration names the subcomponents to be permitted (in documents valid to the target schemas) within any assembly of the type being defined. - -Five elements are used within `model` to define permissible contents of assemblies (elements or objects) being defined. Each of these represents a different object type. Flags are not assigned via `model` but directly in the definition; for the model, we can choose either singles or plurals of named fields or assemblies (i.e., a binary choice between cardinality constraints to be applied). This gives us four choices; additionally, we have the opportunity to use an element `prose`, once inside any assembly's model. - -Among these elements, no single `@named` attribute value (which refers a model component to its definition) may be used more than once. Additionally, no `@group-as` (on a `fields` or `assemblies`) may be reused or be the same as any `@named`. The `prose` element may be used only once. Finally, no value of `@named` or `@group-as` must be the same as a recognized name of an element directly within prose, namely (at present) `p`, `ul`, `ol`, and `pre`. - -With these limitations, a model may be defined to contain any mix of fields and assemblies. - -* `field` refers to a field definition and permits a single occurrence of the indicated field -* `field/@required='yes'` a field component is to be required in a model by any schema based on the metaschema -* `assembly` refers to an assembly definition and permits a single occurrence of the indicated assembly. -* `fields` - same as `field`, but permits the field to be repeated. In the JSON representation the multiple values are represented as any array unless `@address` is given -* `assemblies` - same as `fields`, but for assemblies. In JSON, this construct is also presented as an array unless there is an `@address` -* `prose` refers to a "region of prose", that is, a section of prose text of unspecified length. In XML, prose is represented in conventional fashion as (a sequence of) `

` and list elements (`

    ` or `
      `) perhaps with inline markup (indicating further formatting). For consistency across metaschema applications, the permitted tagging will always be conformant to the same model for prose, managed to reflect (echo) a clean HTML subset. This specification also permits the markup vocabulary to be mapped to a text-based markdown syntax, suitable for use within JSON expressions of the same or similar data. - - -## JSON Enhancement features - -### Use of `key` - -One problem with zero-or-more cardinality as supported by `fields` and `assemblies` is that in JSON, no suitable structure is available for the inclusion of truly arbitrary but repeatable properties or 'contents' (as to its structural type) on an object. The closest thing is an array, which can be pulled into use for this -- at the cost of not permitting a JSON property label on items in the array. In order to capture the same information as is transparently available on the XML, it is therefore necessary to 'finesse' the JSON object type: Metaschema does this by mapping each field or assembly in a zero-or-many set, to an array with the corresponding number of items. The name of the objects can thus be captured implicitly, by naming (labeling) their containing array. - -This works, but there are also occasions when a much more concise mapping may also be supported -- if the data can be ensured to follow another rule, namely that data elements (string data) can be known to be uniquely-valued. In these cases there is a different option, namely to promote a flag of a particular known (and controlled) type, to a role as "address" -- which can (incidentally) serve as a label on a JSON property, thus improving both presentation, and addressability. - -Accordingly, `@address` on `field` or `assemblies` indicates that their contents (components, that is each field or assembly in the series) may be addressed using the flag (attribute) of the given name. So if `address='id'`, for example, and an `id` flag is included on the field or assemply, such flag is assumed to be unique and validable as such (at least within the scope of its parent or containing structure), thus making it suitable for use as a label; consequently, in JSON, the field or assembly can be represented as a labeled property (of an object) rather than an unlabeled member of an array (of similar objects). This both reduces the data footprint and renders the data more addressable via key constructs such as identifiers. - -To support this, flags used as addresses should be declared as type `ID`, providing "an extra layer of protection". On the JSON side, validating the uniqueness of these values (on same-named properties across document scope) remains TBD. - - - -``` - -``` - -``` -Water (H<sub>2</sub>0 -``` - -``` -"title" : "Water (H~~2~~0)" -``` - +# Metaschema Syntax + +The following is an approximate outline of the Metaschema module syntax. Each element and attribute links to the specific specification section describing the element. Attribute value choices are indicated where possible, with default values highlighted. + +{{< rawhtml >}} +
      +
      + <-- ############# -->
      + <-- Module Header -->
      + <-- ############# --> +
      <METASCHEMA xmlns="http://csrc.nist.gov/ns/oscal/metaschema/1.0"
      +
      abstract="yes|no"> (default: no)
      + +
      <schema-name>string</schema-name>
      + +
      <schema-version>string</schema-version>
      +
      <short-name>string</short-name>
      +
      <namespace>uri</namespace>
      +
      <json-base-uri>uri</json-base-uri>
      +
      <remarks>markup-multiline</remarks>
      +
      + <-- ############## -->
      + <-- Module Imports -->
      + <-- ############## --> +
      <import href="uri-reference"/>
      +
      + +
      + <-- ##################### -->
      + <-- Top-Level define-flag -->
      + <-- ##################### --> +
      <define-flag name="token"
      + +
      as-type="token" (default: string)
      + +
      default="string"
      + +
      deprecated="string"
      + +
      scope="global|local"> (default: global)
      + +
      <formal-name>string</formal-name>
      + +
      <description>string</description>
      + +
      +
      <prop name="token" value="token"
      + +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      + +
      <use-name>token</use-name>
      + +
      <constraint/>
      + +
      <remarks>markup-multiline</remarks>
      + +
      <example/>
      +
      </define-flag>
      +
      + + +
      + <-- ######################### -->
      + <-- Top-Level define-assembly -->
      + <-- ######################### --> +
      <define-assembly name="token"
      + +
      deprecated="string"
      + +
      scope="global|local"> (default: global)
      + +
      <formal-name>string</formal-name>
      + +
      <description>string</description>
      + +
      +
      <prop name="token" value="token"
      + +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      + +
      <use-name>token</use-name>
      + +
      <root-name>token</root-name>
      + +
      +
      <json-key flag-ref="token"/>
      +
      + +
      + <-- Flag Instance -->
      +
      <flag ref="token"
      + +
      required="yes|no" (default: no)
      + +
      deprecated="string">
      + +
      <formal-name>string</formal-name>
      + +
      <description>string</description>
      + +
      +
      <prop name="token" value="token"
      + +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      + +
      <use-name>token</use-name>
      + +
      <remarks>markup-multiline</remarks>
      +
      </flag>
      +
      + +
      + <-- Inline Flag Definition -->
      +
      <define-flag name="token"
      + +
      as-type="token" (default: string)
      + +
      default="string"
      + +
      required="yes|no" (default: no)
      + +
      deprecated="string">
      + +
      <formal-name>string</formal-name>
      + +
      <description>string</description>
      + +
      +
      <prop name="token" value="token"
      + +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      + +
      <constraint/>
      + +
      <remarks>markup-multiline</remarks>
      + +
      <example/>
      +
      </define-flag>
      +
      +
      + +
      <model/>
      + +
      + <-- Assembly Instance -->
      +
      <assembly ref="token"
      + +
      min-occurs="non-negative-integer" (default: 0)
      + +
      max-occurs="positive-integer|unbounded" (default: 1)
      + +
      deprecated="string">
      + +
      <formal-name>string</formal-name>
      + +
      <description>string</description>
      + +
      +
      <prop name="token" value="token"
      + +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      + +
      <use-name>token</use-name>
      + +
      +
      <group-as name="token"
      + +
      in-json="ARRAY|SINGLETON_OR_ARRAY|BY_KEY" (default: SINGLETON_OR_ARRAY)
      + +
      in-xml="GROUPED|UNGROUPED"/> (default: UNGROUPED)
      +
      + +
      <remarks>markup-multiline</remarks>
      +
      </assembly>
      +
      + +
      + <-- Field Instance -->
      +
      <field ref="token"
      + +
      min-occurs="non-negative-integer" (default: 0)
      + +
      max-occurs="positive-integer|unbounded" (default: 1)
      + +
      in-xml="WRAPPED|UNWRAPPED" (default: WRAPPED)
      + +
      deprecated="string">
      + +
      <formal-name>string</formal-name>
      + +
      <description>string</description>
      + +
      +
      <prop name="token" value="token"
      + +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      + +
      <use-name>token</use-name>
      + +
      +
      <group-as name="token"
      + +
      in-json="ARRAY|SINGLETON_OR_ARRAY|BY_KEY" (default: SINGLETON_OR_ARRAY)
      + +
      in-xml="GROUPED|UNGROUPED"/> (default: UNGROUPED)
      +
      + +
      <remarks>markup-multiline</remarks>
      +
      </field>
      +
      + +
      + <-- Inline Assembly Definition -->
      +
      <define-assembly/>
      +
      + +
      + <-- Inline Field Definition -->
      +
      <define-field/>
      +
      + +
      + <-- Choice -->
      +
      <choice/>
      +
      + +
      + <-- Any -->
      +
      <any/>
      +
      +
      </model>
      +
      +
      <constraint/>
      +
      <remarks>markup-multiline</remarks>
      +
      <example/>
      +
      </define-assembly>
      +
      + + +
      + <-- ###################### -->
      + <-- Top-Level define-field -->
      + <-- ###################### --> +
      <define-field name="token"
      + +
      as-type="token" (default: string)
      + +
      default="string"
      + +
      collapsible="yes|no" (default: no)
      + +
      deprecated="string"
      + +
      scope="global|local"> (default: global)
      +
      <formal-name>string</formal-name>
      +
      <description>string</description>
      +
      +
      <prop name="token" value="token"
      +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      +
      <use-name>token</use-name>
      + +
      +
      <json-key flag-ref="token"/>
      +
      + +
      +
      <json-value-key>token</json-value-key>
      +
      + +
      +
      <json-value-key-flag flag-ref="token"/>
      +
      + +
      + <-- Flag Instance -->
      +
      <flag ref="token"
      + +
      required="yes|no" (default: no)
      + +
      deprecated="string">
      + +
      <formal-name>string</formal-name>
      + +
      <description>string</description>
      + +
      +
      <prop name="token" value="token"
      + +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      + +
      <use-name>token</use-name>
      + +
      <remarks>markup-multiline</remarks>
      +
      </flag>
      +
      + +
      + <-- Inline Flag Definition -->
      +
      <define-flag name="token"
      + +
      as-type="token" (default: string)
      + +
      default="string"
      + +
      required="yes|no" (default: no)
      + +
      deprecated="string">
      + +
      <formal-name>string</formal-name>
      + +
      <description>string</description>
      + +
      +
      <prop name="token" value="token"
      + +
      namespace="uri"/> (default: http://csrc.nist.gov/ns/oscal/metaschema/1.0)
      +
      + +
      <constraint/>
      + +
      <remarks>markup-multiline</remarks>
      + +
      <example/>
      +
      </define-flag>
      +
      +
      <constraint/>
      +
      <remarks>markup-multiline</remarks>
      +
      <example/>
      +
      </define-field>
      +
      +
      </METASCHEMA>
      +
      +
      +{{< /rawhtml >}} diff --git a/website/content/specification/syntax/constraints.md b/website/content/specification/syntax/constraints.md new file mode 100644 index 000000000..e20806adc --- /dev/null +++ b/website/content/specification/syntax/constraints.md @@ -0,0 +1,44 @@ +--- +title: "Constraints" +description: "" +weight: 50 +--- + +# Constraints + +**Note: This section of the specification is still a work in progress.** + +TODO: P3: Address issue https://github.com/usnistgov/metaschema/issues/325 + +## Common Constraint Data + +## Enumerated values + +Additionally, flags may be constrained to a set of known values listed in advance. + +This restriction can be either: + +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: + +```xml + + Hash algorithm + Method by which a hash is derived + + + Documentation for one permissible option. + Documentation for another permissible option. + + ... +``` + +## `define-flag` constraints + +## `define-field` constraints + +## `define-assembly` constraints diff --git a/website/content/specification/syntax/definitions.md b/website/content/specification/syntax/definitions.md new file mode 100644 index 000000000..5aa76c142 --- /dev/null +++ b/website/content/specification/syntax/definitions.md @@ -0,0 +1,580 @@ +--- +title: "Definitions" +description: "" +weight: 20 +--- + +# Definitions + +A *definition* in a *Metaschema module* declares a reusable [*information element*](/specification/glossary/#information-element) within an [*information model*](/specification/glossary/#information-model). + +In graph theoretical terms, a *definition* provides a declaration of an graph *node* and any associated *edges* that form a given subgraph shape. + +In object-oriented terms, a *definition* provides a declaration of a *class*, along with any associated *class members*. + +The following subsections describe the [common syntax](#common-definition-data) for all *definition* types, followed by the semantic and syntax details of each type of *definition*. The 3 types of *definitions* are [``](#top-level-define-flag), [``](#top-level-define-field), and [``](#top-level-define-assembly). + +## Common Definition Data + +All *definition* types share a common syntax comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@name`](#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| [`@scope`](#scope) | `local` or `global` | optional | `global` | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | +| [``](#example) | special | 0 to ∞ | + +These attributes and elements are described in the following subsections. + +### `@deprecated` Version + +The optional `@deprecated` attribute communicates that use of the given *information element* implemented by the *definition* is intended to be discontinued, starting with the *information model* revision indicated by the attribute's value. + +This attribute's value MUST be a version [string](/specification/datatypes/#string) that is equal to or comes before the [``](/specification/syntax/module/#schema-version) declared in the *Metaschema module* *header*. + +{{}} +Declaring the `@deprecated` attribute communicates to content creators that all use of the annotated *information element* is to be avoided. This annotation can be used in documentation generation and in Metaschema-aware tools that provide context around use of the definition. +{{}} + +The following example illustrates deprecating the flag named `flag-name` starting with the *information model* semantic version `1.1.0`. + +```xml {linenos=table,hl_lines=[3]} + +``` + +### `@name` + +The `@name` attribute provides the definition's identifier, which can be used in other parts of a module, or in an importing *Metaschema module*, to reference the definition. + +This attribute's value MUST be a [token](/specification/datatypes/#token) that is unique among sibling top-level flag definitions. + +**Note:** The names of flags, fields, and assemblies are expected to be maintained as separate identifier sets. This allows a *flag definition*, a *field definition*, and an *assembly definition* to each have the same name in a given *Metaschema module*. + +### `@scope` + +The optional `@scope` attribute is used to communicate the intended visibility of the definition when accessed by another module through an [``](/specification/syntax/module/#import) element. + +- `global` - Indicates that the definition MUST be made available for reference within importing modules. Definitions in the same and importing modules can reference it. This is the default behavior when `@scope` is not declared. +- `local` - Indicates that the definition MUST NOT be made available for reference within importing modules. Only definitions in the same module can reference it. + +Note: References to definitions in the same module are always possible regardless of scope. + +The scope of a definition affects how the [definition's name is resolved](/specification/syntax/module/#definition-name-resolution). + +### `` + +The optional `` element provides a human-readable, short string label for the definition for use in documentation. + +{{}} +The `` label is intended to provide an easy to recognize, meaningful name for the definition. + +While not required, it is best practice to include a ``. +{{}} + +### `` + +The optional `` element is a [single line of markup](/specification/datatypes/#markup-line) that describes the semantic meaning and use of the definition. + +{{}} +The description ties the definition to the related information element concept in the information domain that the definition is representing. This information is ideal for use in documentation. + +While not required, it is best practice to include a ``. +{{}} + +### `` + +The optional `` element provides a structure for declaring arbitrary properties, which consist of a `@namespace`, `@name`, and `@value`. + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| `@namespace` | [`uri`](/specification/datatypes/#uri) | optional | `http://csrc.nist.gov/ns/oscal/metaschema/1.0` | +| `@name` | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| `@value` | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +The `@name` and `@namespace` is used in combination to define a semantically unique name, represented by the `@name` attribute, within the managed namespace defined by the `@namespace` attribute. If the `@namespace` attribute is omitted, the `@name` MUST be considered in the `http://csrc.nist.gov/ns/oscal/metaschema/1.0` namespace. + +The `@value` attribute represents the lexical value assignment for the semantically unique name represented by the combination of the `@name` and `@namespace`. The lexical values of the `@value` attribute may be restricted for the specific semantically unique name, but such restrictions are not enforced directly in this model. + +{{}} +A property is useful for annotating a definition with additional information that might describe, in a structured way, the semantics, use, nature, or other significant information related to the definition. In many cases, a property might be used to tailor generated documentation or to support an experimental, non-standardized feature in Metaschema. +{{}} + +### Naming and `` + +The optional `` changes the *effective name* to use for the information element in a data model. + +The `` element is optional and MAY only occur once. + +By default the *effective name* of the information element in a data model is taken from the `@name` attribute. The `` value overrides this behavior. + +{{}} +Use of a `` frees the module maintainer allowing them to use a sensible `@name` for the definition, while providing control over the name used in an instance of the definition in a data model. +{{}} + +The first matching condition determines the *effective name* for the definition: + +1. A `` is provided on the definition. The *effective name* is the value of the `` element on the definition. +1. No `` is provided on the definition. The *effective name* is the value of the `@name` attribute on the definition. + +For example: + +```xml {linenos=table,hl_lines=[2]} + + flag-b + +``` + +In the example above, the *effective name* of the definition is `flag-b`. If the `` was omitted, the *effective name* would be `flag-a`. + +The following content is valid to the model above. + +{{< tabs JSON YAML XML >}} +{{% tab %}} +```json +{ + "field": { + "flag-b": "value" + } +} +``` +{{% /tab %}} +{{% tab %}} +```yaml +--- +field: + flag-b: "value" +``` +{{% /tab %}} +{{% tab %}} +```xml + +``` +{{% /tab %}} +{{% /tabs %}} + +### `` + +The optional `` element provides a place to add notes related to the use of the definition. Remarks can be used to clarify the semantics of the definition in specific conditions, or to better describe how the definition may be more fully utilized within a model. + +The `` element is optional and may occur multiple times. +It supports an optional `@class` attribute that can be used to identify format specific specific remarks, to be handled appropriately (or ignored when not useful) in a downstream application. Valid values for `@class` are: +- `XML`: The remark applies to the XML format binding. +- `JSON`: The remark applies to the JSON or YAML format bindings. +### `` + +The optional `` element is used to provide inline examples, which illustrate the use of the information element being defined. Examples are provided in XML, which can then be automatically converted into other formats. + +The `example` element is optional and may occur multiple times. + + +## top-level `` + +A *flag definition*, represented by the `` element, is used to declare a reusable [flag](/specification/glossary/#flag) within a Metaschema module. + +A *flag definition* provides the means to implement a simple, named [*information element*](/specification/glossary/#information-element) with a value. + +{{}} +*Flag definitions* are leaf nodes in a Metaschema-based model that are intended to represent granular particles of identifying and qualifying information. +{{}} + +The flag's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) identified by the `@as-type` attribute. + +The syntax of a flag is comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@as-type`](#as-type) | [`token`](/specification/datatypes/#token) | optional | [`string`](/specification/datatypes/#string) | +| [`@default`](#default) | [`string`](/specification/datatypes/#string) | optional | *(no default)* | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@name`](#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| [`@scope`](#scope) | `local` or `global` | optional | `global` | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [``](/specification/syntax/constraints/#define-flag-constraints) | special | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | +| [``](#example) | special | 0 to ∞ | + +The attributes and elements specific to the `` are described in the following subsections. The elements and attributes common to all *definitions* are [defined earlier](#common-definition-data) in this specification. + +### `@as-type` + +The `@as-type` attribute declares the type of the flag's value. If not provided, the default value is `string`. + +The `@as-type` attribute must have a value that corresponds to one of the [simple data types](/specification/datatypes/#simple-data-types). As a result, markup in flag values is not permitted. + +### `@default` + +The `@default` attribute specifies the default value for the flag. When a flag is specified as an optional child of a `` or ``, this value SHOULD be considered set for a content instance if the flag is omitted in that instance. + +## `` + +Both the [``](#top-level-define-field) and [``](#top-level-define-assembly) definition types support the definition of a ``. + +A `` is used to identify a *flag instance* on the *definition* that is used to group a collection of [*named model instances*](/specification/syntax/instances/#named-model-instances) with the same name related to the *definition* when serializing to the JSON format. This is controlled using the [`group-as`](/specification/syntax/instances/#group-as) element using the [`in-json="BY_KEY"`](/specification/syntax/instances/#in-jsonby_key) attribute value. + +For more information see [using ``](/specification/syntax/instances/#in-jsonby_key). + +## top-level `` + +A *field definition*, represented by the `` element, is used to declare a reusable [field](/specification/glossary/#field) within a metaschema module. + +A *field definition* provides the means to implement a complex named [*information element*](/specification/glossary/#information-element) with a value and an optional set of [*flag instances*](/specification/syntax/instances/#flag-instance). + +{{}} +A *field definition* is an edge node in a Metaschema-based model. *Fields* are typically used to provide supporting information for a containing [*assembly definition*](/specification/syntax/definitions/#top-level-define-assembly). The optional set of *flag instances* declared on a *field definition*, typically characterize or identify the fields value. With optional use of flags, a field can be more or less complex, depending on the modeling need. +{{}} + +The field's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) or [markup data types](/specification/datatypes/#markup-data-types) identified by the `@as-type` attribute. + +The syntax of an *field definition* is comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@as-type`](#as-type-1) | [`token`](/specification/datatypes/#token) | optional | [`string`](/specification/datatypes/#string) | +| [`@collapsible`](#collapsible) | `yes` or `no` | optional | `no` | +| [`@default`](#default-1) | [`string`](/specification/datatypes/#string) | optional | *(no default)* | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@name`](#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| [`@scope`](#scope) | `local` or `global` | optional | `global` | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [`json-key`](#json-key) | special | 0 or 1 | +| [`json-value-key`](#json-value-key) or
      [`json-value-key-flag`](#json-value-key-flag) | special | 0 or 1 | +| [`flag`](#flag-instance-children) or
      [`define-flag`](#define-flag-inline-definition) | special | 0 or ∞ | +| [``](/specification/syntax/constraints/#define-flag-constraints) | special | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | +| [``](#example) | special | 0 to ∞ | + +The attributes and elements specific to the `` are described in the following subsections. The elements and attributes common to all definitions are [defined earlier](#common-definition-data) in this specification. + +### `@as-type` + +The optional `@as-type` attribute declares the type of the field's value. If not provided, the default type is `string`. + +The `@as-type` attribute must have a value that corresponds to one of the built in [simple data types](/specification/datatypes/#simple-data-types) or [markup data types](/specification/datatypes/#markup-data-types). + +### `@collapsible` + +The optional `@collapsible` attribute controls a JSON and YAML specific behavior that allows multiple fields having the same set of flag values to be collapsed into a single object with a value property that is an array of values. This makes JSON and YAML formatted data more concise. + +If `@collapsible` is not specified, the default value is `no`. + +The following behaviors are REQUIRED to be used for each value of `@collapsible`. + +- `no` - Do not collapse. This is the default behavior when `@collapsible` is not declared. +- `yes` - Collapse values that have flags with equivalent values. + +A flag value is equivalent if the value, or default value if not provided, is an exact match. A non-default flag is considered to have no value and will match the same flag on another instance that has no value. + +Field instances whose flags all match are considered to be in the same *collapse group*. Collapsing works by combining the values for all the instances in the the same *collapse group*. + +When collapsing values in the same *collapse group* the ordering of the field values MUST be in the same order as their original field instances. The ordering of all *collapse groups* MUST follow the ordering of the first field instance added to the collapse group. + +For example, given field instances in the sequence `{ A, B, C, D }`, if `{ A, C }` are a collapse group, and `{ B, D }` are a different collapse group. Then `{ A, C }` would be ordered before `{ B, D }`, since `A` is ordered before `B`. + +Note: Collapsing may affect the relative ordering of field instances. If two field instances are non-adjacent and their flags match, then the later field instance will be moved to be adjacent to the first. **Do not use the collapsible feature if maintaining field sequences is important to your use.** + +An example a collapsible field definition might look like the following. + +```xml + + assembly + + + + + + + + + +``` + +An example set of content instances follow. XML is provided first to illustrate the use of uncollapsed fields, since this feature applies to JSON and YAML only. The JSON and YAML collapsed versions follow. + +```xml {linenos=table,hl_lines=[2,4]} + + field-value-1 + field-value-2 + field-value-3 + +``` + +The XML example above illustrates 2 fields, on lines 2 and 4, which will be collapsed together into the same *collapse group* in the resulting JSON and YAML conversion. This is because they have the same flag values: `a` for the flag named `flag-default-a`, `required 1` for the flag named `flag-required`, and no value for the flag named `flag-optional`. The field on line 3 would be in a second *collapse group*. + +When converted to JSON or YAML, these fields will be collapsed based on their collapse grouping, resulting in the following content instances. + +{{< tabs JSON YAML >}} +{{% tab %}} +```json {linenos=table,hl_lines=["4-7"]} +{ +"assembly": { + "fields": [ + { + "flag-required": "required 1", + "STRVALUE": [ "field-value-1", "field-value-3"] + }, + { + "flag-required": "required 2", + "STRVALUE": "field-value-2" + } + ] +} +``` +{{% /tab %}} +{{% tab %}} +```yaml {linenos=table,hl_lines=["4-7"]} +--- +assembly: + fields: + - flag-required: "required 1" + STRVALUE: + - "field-value-1" + - "field-value-3" + - flag-required: "required 2" + STRVALUE: "field-value-2" +``` +{{% /tab %}} +{{% /tabs %}} + +If the JSON or YAML instance is converted back to XML, the sequencing of the fields will change due to use of the collapsible feature as follows. + +```xml {linenos=table,hl_lines=["2-3"]} + + field-value-1 + field-value-3 + field-value-2 + +``` + +In the example above, the fields from the first *collapse group* would appear before the fields from the second *collapse group*. This is because the resulting JSON and YAML instance has no way of indicating the original sequencing, so it must rely on the sequencing provided by the ordering of the *collapse groups* and the values within each group. + +### `@default` + +The `@default` attribute specifies the default value for the field. When a flag is specified as an optional child of a `` or ``, this value should be considered set for a content instance if the field is omitted in that instance. + +A `@default`value MUST only be provided when the data type specified by the `@as-type` is a [simple data types](/specification/datatypes/#simple-data-types). Specifying a `@default` value for a [markup data type](/specification/datatypes/#markup-data-types) MUST result in a Metaschema format error. + +Implementations when writing content instances MAY omit writing default values in order to produce a more concise expression of the content. + + +### `` Instance Children + +A field may have zero or more flag instance children. + +See [flag instances](/specification/syntax/instances/#flag-instance) + +### `` Inline Definition + +See [inline ``](/specification/syntax/inline-definitions/#inline-define-flag). + +### JSON Value Keys + +TODO: P2: discuss use only when flags may be present. +TODO: P2: Address issue https://github.com/usnistgov/metaschema/issues/316 + +In XML, the value of a field appears as the textual data content of the field's element. In JSON and YAML, a property name is needed for the value. The `` and `` elements provide a means to control the behavior of how this value is represented. + +If no `` or `` element is declared, a property name value will be chosen based on the data type as follows: + - If the field's `@as-type` is `markup-line`, then the property name will be `RICHTEXT`. + - If the field's `@as-type` is `markup-multiline`, then the property name will be `prose`. + - Otherwise, the property name will be `STRVALUE`. + +This logic may result in less than ideal property names. Metaschema provides the ` and `` elements to override this behavior. Use of these elements are mutually exclusive. + +The following subsections describe the use of these elements. + +#### `` + +The `` element can be declared to set the property name for the field's value. Its text value child MUST be used as the property name for the field's value. + +For example: + +```xml {linenos=table,hl_lines=[5]} + + assembly + + + value + + + + + +``` + +Would allow the following content in JSON and YAML. + +{{< tabs JSON YAML >}} +{{% tab %}} +```json {linenos=table,hl_lines=[6]} +{ + "assembly": { + "fields": [ + { + "flag-default-a": "b", + "value": "value1" + } + ] + } +} +``` +{{% /tab %}} +{{% tab %}} +```yaml {linenos=table,hl_lines=[5]} +--- +assembly: + fields: + - flag-default-a: "b" + value: "value1" +``` +{{% /tab %}} +{{% /tabs %}} + +#### `` + +The `` element can be declared to use the value of specific flag on the field as the property name for the field's value. + +The `@flag-name` attribute MUST reference the [name](#name) of a flag on the field whose value is to be used as the property name. + +This results in a property that is a combination of the referenced flag's value and the field's value. + +For example: + +TODO: P2: complete this example. + +## top-level `` + +An assembly definition, represented by the `` element, is used to declare a reusable [assembly](/specification/glossary/#assembly) within a Metaschema module. + +An assembly definition provides the means to implement a complex, composite, named [*information element*](/specification/glossary/#information-element) that collects and organizes other information elements, with no value of its own. + +An assembly definition consists of an optional set of [*flags*](/specification/syntax/instances/#flag-instance) and an optional sequence of [model instances](/specification/syntax/instances/#model-instances). + +{{}} +An *assembly definition* is a compositional node in a Metaschema-based model. Assemblies are typically used to represent complex data objects, combining multiple information elements together into a composite object representing a larger semantic concept. An assembly's flag instances will typically characterize or identify this composite object, while its model instances represent the information being composed. +{{}} + +An assembly is similar to a field, except it contains structured content (objects or elements), not text or unstructured "rich text". The contents permitted in a particular (type of) assembly are indicated in its `model` element. + +An assembly definition has no value, so the `@as-type` and `@default` attributes are not permitted. + +The syntax of an *assembly definition* is comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@name`](#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| [`@scope`](#scope) | `local` or `global` | optional | `global` | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) or
      [``](#root-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [`json-key`](#json-key) | special | 0 or 1 | +| [`flag`](#flag-instance-children-1) or
      [`define-flag`](#define-flag-inline-definition-1) | special | 0 or ∞ | +| [``](#model) | special | 0 or 1 | +| [``](/specification/syntax/constraints/#define-flag-constraints) | special | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | +| [``](#example) | special | 0 to ∞ | + +The attributes and elements specific to the `` are described in the following subsections. The elements and attributes common to all definitions are [defined earlier](#common-definition-data) in this specification. + +### `` + +Declares the name to use when using the assembly as a top-level information element. Indicates that the assembly is an allowable root. + +For example: + +```xml {linenos=table,hl_lines=[2]} + + assembly + +``` + +Would allow the following content in JSON, YAML, and XML. + +{{< tabs JSON YAML XML >}} +{{% tab %}} +```json {linenos=table,hl_lines=[2]} +{ + "assembly": { } +} +``` +{{% /tab %}} +{{% tab %}} +```yaml {linenos=table,hl_lines=[2]} +--- +assembly: - +``` +{{% /tab %}} +{{% tab %}} +```xml {linenos=table,hl_lines=[1]} + +``` +{{% /tab %}} +{{% /tabs %}} + +### `` Instance Children + +An assembly may have zero or more flag instance children. + +See [flag instances](/specification/syntax/instances/#flag-instance). + +### `` Inline Definition + +An assembly may have zero or more flag instance children, which can be inline definitions. + +See [inline ``](/specification/syntax/inline-definitions/#inline-define-flag). + +### `` + +The `` element is used to establish the assembly's model. To do this, zero or more [model instances](/specification/syntax/instances/#model-instances) are declared. + +Zero or more of the following elements are allowed. + +- [``](/specification/syntax/instances/#field-instance) - Instantiates a globally defined [field definition](#top-level-define-field) as a model instance. +- [``](/specification/syntax/inline-definitions/#inline-define-field) - Defines a [single use field](/specification/syntax/inline-definitions/#inline-define-field) for use as a model instance. +- [``](/specification/syntax/instances/#assembly-instance) - Instantiates a globally defined [assembly definition](#top-level-define-assembly) as a model instance. +- [``](/specification/syntax/inline-definitions/#inline-define-assembly) - Defines a [single use assembly](/specification/syntax/inline-definitions/#inline-define-assembly) for use as a model instance. +- [``](/specification/syntax/instances/#choice-selections) - Declares a mutually exclusive selection of child model instances. +- [``](/specification/syntax/instances/#any) - Declares a placeholder for extra content that is not described by an assembly definition's model. diff --git a/website/content/specification/syntax/inline-definitions.md b/website/content/specification/syntax/inline-definitions.md new file mode 100644 index 000000000..2e511c42d --- /dev/null +++ b/website/content/specification/syntax/inline-definitions.md @@ -0,0 +1,169 @@ +--- +title: "Inline Definitions" +description: "" +weight: 40 +--- + +# Inline Definitions + +*Inline definitions* are a mechanism to both define a named [*information element*](/specification/glossary/#information-element) and instantiate it. In this way, *inline definitions* can be thought of as both [*definitions*](/specification/syntax/definitions/) and [*instances*](/specification/syntax/instances/), sharing most of the data elements of both. + +*Inline definitions* are provided as a convenience to allow single-use *information elements* to declared inline, within other *definitions*. Single-use, inline declarations are easier to maintain than a *top-level definition* that is referenced, since the maintainer doesn't have to trace the reference. + +## Common Inline Definition Data + +All *inline definition* types share a common syntax comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](/specification/syntax/definitions/#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@name`](/specification/syntax/definitions/#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](/specification/syntax/definitions/#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](/specification/syntax/definitions/#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](/specification/syntax/definitions/#prop) | special | 0 to ∞ | +| [``](/specification/syntax/definitions/#remarks) | special | 0 or 1 | +| [``](/specification/syntax/definitions/#example) | special | 0 to ∞ | + +These attributes and elements are based on the [*definition* common data elements](/specification/syntax/definitions/#common-definition-data), since an *inline definition* uses a reduced set of the same data with the same semantics. + +Due to their single use nature, *inline definitions* do not allow the use of `@scope` or ``. +- Use of `scope` is not necessary, since inline definitions are always scoped to the inline context of their use. This inline scoping has equivalent behavior to [`@scope="local"`](/specification/syntax/definitions/#scope). +- Use of a `` is not needed, since strict control of naming is provided by `@name`. + +## Inline `` + +An *inline flag definition*, represented by the `` element, is used to declare a single use, locally scoped [flag](/specification/glossary/#flag) within a [top-level ``](/specification/syntax/definitions/#top-level-define-field), a [top-level ``](/specification/syntax/definitions/#top-level-define-assembly), an [inline ``](#inline-define-field), or an [inline ``](#inline-define-assembly). + +A *inline flag definition* provides the means to implement a simple, named [*information element*](/specification/glossary/#information-element) with a value. + +{{}} +An *inline flag definition* is a leaf node in a Metaschema-based model that is intended to represent a granular particle of identifying and qualifying information. +{{}} + +The flag's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) identified by the `@as-type` attribute. + +The syntax of an *inline flag definition* is comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@as-type`](/specification/syntax/definitions/#as-type) | [`token`](/specification/datatypes/#token) | optional | [`string`](/specification/datatypes/#string) | +| [`@default`](/specification/syntax/definitions/#default) | [`string`](/specification/datatypes/#string) | optional | *(no default)* | +| [`@deprecated`](/specification/syntax/definitions/#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@name`](/specification/syntax/definitions/#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| [`@required`](/specification/syntax/instances/#required) | `yes` or `no` | optional | `no` | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](/specification/syntax/definitions/#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](/specification/syntax/definitions/#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](/specification/syntax/definitions/#prop) | special | 0 to ∞ | +| [``](/specification/syntax/constraints/#define-flag-constraints) | special | 0 or 1 | +| [``](/specification/syntax/definitions/#remarks) | special | 0 or 1 | +| [``](/specification/syntax/definitions/#example) | special | 0 to ∞ | + +These attributes and elements are based on a combination of a reduced set of the data elements provided by the [*top-level flag definition*](/specification/syntax/definitions/#top-level-define-flag) and the [*flag instance*](/specification/syntax/instances/#flag-instance), since an *inline flag definition* uses a reduced set of the same data with the same semantics. + +The elements and attributes common to all *inline definitions* are [defined earlier](#common-inline-definition-data) in this specification. + +## Inline `` + +An *inline field definition*, represented by the `` element, is used to declare a single use, locally scoped [field](/specification/glossary/#field) within a [top-level ``](/specification/syntax/definitions/#top-level-define-assembly) or an [inline ``](#inline-define-assembly). + +A *inline field definition* provides the means to implement a complex named [*information element*](/specification/glossary/#information-element) with a value and an optional set of [*flag instances*](/specification/syntax/instances/#flag-instance). + +{{}} +An *inline field definitions* is an edge node in a Metaschema-based model. *Fields* are typically used to provide supporting information for a containing [*assembly definition*](/specification/syntax/definitions/#top-level-define-assembly). The optional set of *flag instances* declared on an *inline field definition*, typically characterize or identify the fields value. With optional use of flags, a field can be more or less complex, depending on the modeling need. +{{}} + +The fields's value is strongly typed using one of the built in [simple data types](/specification/datatypes/#simple-data-types) or [markup data types](/specification/datatypes/#markup-data-types) identified by the `@as-type` attribute. + +The syntax of an *inline field definition* is comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@as-type`](/specification/syntax/definitions/#as-type-1) | [`token`](/specification/datatypes/#token) | optional | [`string`](/specification/datatypes/#string) | +| [`@collapsible`](/specification/syntax/definitions/#collapsible) | `yes` or `no` | optional | `no` | +| [`@default`](/specification/syntax/definitions/#default-1) | [`string`](/specification/datatypes/#string) | optional | *(no default)* | +| [`@deprecated`](/specification/syntax/definitions/#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@in-xml`](/specification/syntax/instances/#in-xml-1) | `WRAPPED`, `WITH_WRAPPER` or `UNWRAPPED` | optional | `WRAPPED` | +| [`@max-occurs`](/specification/syntax/instances/#max-occurs) | [`positive-integer`](/specification/datatypes/#non-negative-integer) or `unbounded` | optional | 1 | +| [`@min-occurs`](/specification/syntax/instances/#min-occurs) | [`non-negative-integer`](/specification/datatypes/#non-negative-integer) | optional | 0 | +| [`@name`](/specification/syntax/definitions/#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](/specification/syntax/definitions/#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](/specification/syntax/definitions/#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](/specification/syntax/definitions/#prop) | special | 0 to ∞ | +| [`json-key`](/specification/syntax/definitions/#json-key) | special | 0 or 1 | +| [`json-value-key`](/specification/syntax/definitions/#json-value-key) or
      [`json-value-key-flag`](/specification/syntax/definitions/#json-value-key-flag) | special | 0 or 1 | +| [``](/specification/syntax/instances/#group-as) | special | 0 or 1 | +| [`flag`](/specification/syntax/definitions/#flag-instance-children) or
      [`define-flag`](/specification/syntax/definitions/#define-flag-inline-definition) | special | 0 or ∞ | +| [``](/specification/syntax/constraints/#define-flag-constraints) | special | 0 or 1 | +| [``](/specification/syntax/definitions/#remarks) | special | 0 or 1 | +| [``](/specification/syntax/definitions/#example) | special | 0 to ∞ | + +These attributes and elements are based on a combination of a reduced set of the data elements provided by the [*top-level field definition*](/specification/syntax/definitions/#top-level-define-field) and the [*field instance*](/specification/syntax/instances/#field-instance), since an *inline field definition* uses a reduced set of the same data with the same semantics. + +The elements and attributes common to all *inline definitions* are [defined earlier](#common-inline-definition-data) in this specification. + +## Inline `` + +An *inline assembly definition*, represented by the `` element, is used to declare a single use, locally scoped [assembly](/specification/glossary/#assembly) within a [top-level ``](/specification/syntax/definitions/#top-level-define-assembly) or an [inline ``](#inline-define-assembly). + +A *inline assembly definition* provides the means to implement a complex, composite, named [*information element*](/specification/glossary/#information-element) that collects and organizes other information elements, with no value of its own. + +An assembly definition consists of an optional set of [*flags*](/specification/syntax/instances/#flag-instance) and an optional sequence of [model instances](/specification/syntax/instances/#model-instances). + +{{}} +An *inline assembly definition* is a compositional node in a Metaschema-based model. Assemblies are typically used to represent complex data objects, combining multiple information elements together into a composite object representing a larger semantic concept. An assembly's flag instances will typically characterize or identify this composite object, while its model instances represent the information being composed. +{{}} + +An assembly is similar to a field, except it contains structured content (objects or elements), not text or unstructured "rich text". The contents permitted in a particular (type of) assembly are indicated in its `model` element. + +An assembly definition has no value, so the `@as-type` and `@default` attributes are not permitted. + +The syntax of an *inline assembly definition* is comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](/specification/syntax/definitions/#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@max-occurs`](/specification/syntax/instances/#max-occurs) | [`positive-integer`](/specification/datatypes/#non-negative-integer) or `unbounded` | optional | 1 | +| [`@min-occurs`](/specification/syntax/instances/#min-occurs) | [`non-negative-integer`](/specification/datatypes/#non-negative-integer) | optional | 0 | +| [`@name`](/specification/syntax/definitions/#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](/specification/syntax/definitions/#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](/specification/syntax/definitions/#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](/specification/syntax/definitions/#prop) | special | 0 to ∞ | +| [`json-key`](/specification/syntax/definitions/#json-key) | special | 0 or 1 | +| [`json-value-key`](/specification/syntax/definitions/#json-value-key) or
      [`json-value-key-flag`](/specification/syntax/definitions/#json-value-key-flag) | special | 0 or 1 | +| [``](/specification/syntax/instances/#group-as) | special | 0 or 1 | +| [`flag`](/specification/syntax/definitions/#flag-instance-children) or
      [`define-flag`](/specification/syntax/definitions/#define-flag-inline-definition) | special | 0 or ∞ | +| [``](/specification/syntax/constraints/#define-flag-constraints) | special | 0 or 1 | +| [``](/specification/syntax/definitions/#remarks) | special | 0 or 1 | + +These attributes and elements are based on a combination of a reduced set of the data elements provided by the [*top-level assembly definition*](/specification/syntax/definitions/#top-level-define-assembly) and the [*assembly instance*](/specification/syntax/instances/#assembly-instance), since an *inline assembly definition* uses a reduced set of the same data with the same semantics. + +The elements and attributes common to all *inline definitions* are [defined earlier](#common-inline-definition-data) in this specification. + diff --git a/website/content/specification/syntax/instances.md b/website/content/specification/syntax/instances.md new file mode 100644 index 000000000..5adb09509 --- /dev/null +++ b/website/content/specification/syntax/instances.md @@ -0,0 +1,464 @@ +--- +title: "Instances" +description: "Instances" +weight: 30 +--- + +# Instances + +In a Metaschema module, complex information elements are created through composition. Through composition, an information element can be built by indicating which other information elements are used as its constituent parts. + +An *instance* is used to declare an information element *child* within a *parent* information element. Each instance is a *flag instance*, *field instance*, or *assembly instance*, and either references an existing [*top-level definition*](/specification/syntax/definitions/) by name or provides an [*inline definition*](/specification/syntax/inline-definitions/). + +In a Metaschema module, an instance appears inside the definition of its parent information element. +- An *assembly definition* may contain flag, field or assembly instances reflecting the objects to be permitted in that assembly. +- A *field definition* may only include flag instances. +- A Flag definition will never contain instances since flags have no children in the model, only values. + +## Common Instance Data + +The [``](#assembly-instance), [``](#field-instance), and [``](#flag-instance) child elements share a common syntax comprised of the following XML attributes and elements. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@ref`](#ref) | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | + +These attributes and elements are described in the following subsections. + +### `@deprecated` Version + +The optional `@deprecated` attribute communicates that a given compositional use of the referenced information element is intended to be discontinued starting with the specified version. + +This version is a reference to the [``](/specification/syntax/module/#schema-version) declared in the module header. + +If both the definition and the instance declare a `@deprecated` version, the value provided by the instance MUST override the value provided by the definition. + +{{}} +Declaring the `@deprecated` attribute communicates to content creators that the use of a given instance of the information element is to be avoided. This is more fine-grained than deprecating all uses of the information element, which is supported by the [`@deprecated`](#deprecated-version) attribute on the referenced definition. + +This annotation can be used in documentation generation and in Metaschema-aware tools that provide context around use of the instance. +{{}} + +For example, deprecating the use of the flag named `id` within the `computer` assembly starting with the model version `1.1.0` would be represented as follows. + +```xml {linenos=table,hl_lines=[6]} + + + computer + + +``` + +### `@ref` + +The `@ref` attribute references the top-level definition that the instance represents through composition. The name indicated by the `@ref` attribute MUST be a definition of the corresponding type declared in the containing module or a globally scoped definition in an imported module. See [Definition Name Resolution](/specification/syntax/module/#definition-name-resolution). + +The instance type corresponds with the definition type as follows. + +| Instance Type | Top-Level Definition Type | +|:--- |:--- | +| [``](#flag-instance) | [``](/specification/syntax/definitions/#top-level-define-flag) | +| [``](#field-instance) | [``](/specification/syntax/definitions/#top-level-define-field) | +| [``](#assembly-instance) | [``](/specification/syntax/definitions/#top-level-define-assembly) | + +**Note:** The names of flags, fields, and assemblies are expected to be maintained as separate identifier sets. This allows a flag, field, and an assembly definition to each have the same name in a given Metaschema module. + +### `` + +The optional `` element provides a human-readable, short string label for the instance for use in documentation. + +If provided, this formal name MUST override the `` declared on the corresponding definition, if a `` is declared there. If not provided, the effective formal name of the instance MUST be the `` declared on the definition. If neither the instance or the definition provide a ``, then the instance MUST NOT have a declared formal name. + +{{}} +The `` label is intended to provide an easy to recognize, meaningful name for the instance. This element can be used when the formal name of the instance differs in use from the formal name declared by the referenced definition. + +While not required, it is best practice to include a `` when the use case of the instance is more specialized than the intended use described by the definition. +{{}} + +### `` + +The optional `` element is a [single line of markup](/specification/datatypes/#markup-line) that describes the semantic meaning and use of the instance. This information is ideal for use in documentation. + +If provided, this description MUST override the `` declared on the corresponding definition, if a `` is declared there. If not provided on an instance, the effective description of the instance MUST be the `` declared on the definition. If neither the instance or the definition provide a ``, then the instance MUST NOT have a declared description. + +{{}} +The description ties the instance to the related information element concept in the information domain that the instance is representing. This element can be used when the description of the instance differs in use from the description declared by the referenced definition. + +While not required, it is best practice to include a `` when the use case of the instance is more specialized than the intended use described by the definition. +{{}} + +### `` + +The optional `` element provides a structure for declaring arbitrary properties, which consist of a `@namespace`, `@name`, and `@value`. + +This data element uses the same syntax as the [`` allowed on a definition](/specification/syntax/definitions/#prop). When used on an instance, the set of properties MUST apply only to the instance. + +Properties declared on the definition MAY be inherited by the instance. Metaschema does not define any general rules for how to handle overlapping and conflicting properties. How to handle these cases SHOULD be defined and documented for each property. + +{{}} +A property is useful for annotating an instance with additional information that might describe, in a structured way, the semantics, use, nature, or other significant information related to the instance. In many cases, a property might be used to tailor generated documentation or to support an experimental, non-standardized feature in Metaschema. +{{}} + +### Naming and `` + +Similar to the [``](/specification/syntax/definitions/#naming-and-use-name) allowed on the referenced definition, the optional `` on a instance changes the *effective name* to use for the information element in a compositional data model. + +The `` element is optional and MAY only occur once. + +By default the *effective name* of the information element in a data model is taken from the [*effective name* of the definition](/specification/syntax/definitions/#naming-and-use-name). The `` value overrides this behavior for the instance only. + +{{}} +Use of a `` frees the module maintainer allowing them to use a sensible *effective name* for the instance in a data model. +{{}} + +The first matching condition determines the *effective name* for the definition: + +1. A `` is provided on the instance. The *effective name* is the value of the `` element on the instance. +1. A `` is provided on the definition. The *effective name* is the value of the `` element on the definition. +1. No `` is provided on the definition. The *effective name* is the value of the `@name` attribute on the definition. + +For example: + +```xml + + flag-b + + + + flag-c + + +``` + +In the example above, the *effective name* of the definition is `flag-c`. If the `` was omitted on the instance, the *effective name* would be `flag-b`. If the `` was also omitted on the definition, the *effective name* would be `flag-a`. + +The following content is valid to the model above. + +{{< tabs JSON YAML XML >}} +{{% tab %}} +```json +{ + "field": { + "flag-c": "value" + } +} +``` +{{% /tab %}} +{{% tab %}} +```yaml +--- +field: + flag-c: "value" +``` +{{% /tab %}} +{{% tab %}} +```xml + +``` +{{% /tab %}} +{{% /tabs %}} + +### `` + +The optional `` element provides a place to add notes related to the use of the instance. Remarks can be used to clarify the semantics of the instance in specific conditions, or to better describe how the instance may be more fully utilized within a model. + +The `` element is optional and may occur multiple times. + +## `` Instance + +A *flag instance* is used to declare that a top-level [*flag definition](/specification/syntax/definitions/#top-level-define-flag) is part of the model of a *field definition* or *assembly definition*. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@ref`](#ref) | [`token`](/specification/datatypes/#token) | required | *(no default)* | +| [`@required`](#required) | `yes` or `no` | optional | `no` | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | + +The attributes and elements specific to a `` instance are described in the following subsections. The elements and attributes common to all instance types are [defined earlier](#common-instance-data) in this specification. + +The [`@ref`](#ref) attribute MUST reference a top-level *flag definition's* [`@name`](/specification/syntax/definitions/#name) that is in scope. See [Definition Name Resolution](/specification/syntax/module/#definition-name-resolution) for a detailed explanation of definition name scoping. + +The following is an example of a *flag instance*. + +```xml {linenos=table,hl_lines=[4]} + + + computer + + +``` + +### `@required` + +The optional `@required` attribute declares if the flag is required to be provided in an associated content instance. + +The following behaviors are REQUIRED to be used for each value of `@required`. + +- `no` - Do not require the flag to be present in content. This is the default behavior when `@required` is not declared. +- `yes` - Require the flag to be present in content. Content missing the flag and its value will be considered invalid. + +## Model Instances + +A *model instance* is used to declare a relationship to other information elements in an assembly definition's model. + +There are 5 kinds of model instances, which can be declared as part of the assembly's model. + +- [``](#field-instance) - Instantiates a globally defined [field definition](/specification/syntax/definitions/#top-level-define-field) as a model instance. +- [``](/specification/syntax/inline-definitions/#inline-define-field) - Defines a [single use field](/specification/syntax/inline-definitions/#inline-define-field) for use as a model instance. +- [``](#assembly-instance) - Instantiates a globally defined [assembly definition](/specification/syntax/definitions/#top-level-define-assembly) as a model instance. +- [``](/specification/syntax/inline-definitions/#inline-define-assembly) - Defines a [single use assembly](/specification/syntax/inline-definitions/#inline-define-assembly) for use as a model instance. +- [``](#choice-selections) - Declares a [mutually exclusive selection](#choice-selections) of child model instances. +- [``](#any) - Declares a [placeholder for extra content](#any) that is not described by an assembly definition's model. + +The ``, ``, ``, `` model instance types are considered [*named model instances*](#named-model-instances), since they all instantiate either a [top-level](/specification/syntax/definitions/) or [inline](/specification/syntax/inline-definitions/) definition that represent a named information element within an assembly's model. + +The `` and `` elements represent special constructs which differ significantly in their semantics from the named model instances. + +These different types of model instances are discussed in the following subsections. + +## Named Model Instances + +The ``, ``, ``, `` model instance types are considered [*named model instances*](#named-model-instances), which instantiate a definition within an assembly's model. + +The `` and `` elements are used to instantiate a referenced [top-level definition](/specification/syntax/definitions/). + +The `` and `` elements are used to both declare a single use [inline definition](/specification/syntax/inline-definitions/) and also instantiate the declared definition. + +### Common Named Model Instance Data + +All named model instances share a common common syntax comprised of the following XML attributes and elements. This syntax builds on the [common syntax and semantics](#common-instance-data) shared by all instance types. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@max-occurs`](#ref) | [`positive-integer`](/specification/datatypes/#non-negative-integer) or `unbounded` | optional | `1` | +| [`@min-occurs`](#ref) | [`non-negative-integer`](/specification/datatypes/#non-negative-integer) | optional | `0` | +| [`@ref`](#ref) | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [``](#group-as) | special | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | + +The following subsections describe the XML attributes and elements that are specific to named model instances. + +#### `@max-occurs` + +The optional `@max-occurs` attribute declares the maximum cardinality bound for the named model instance, which defaults to `1`. + +This value can be either: + +- a [`positive-integer`](/specification/datatypes/#non-negative-integer) value, representing a bounded maximum cardinality; or +- the `unbounded` value, representing a maximum cardinality with no upper bound. + +#### `@min-occurs` + +The optional `@min-occurs` attribute declares the minimum cardinality bound for the named model instance as a [`non-negative-integer`](/specification/datatypes/#non-negative-integer) value, which defaults to `0`. + +#### `` + +The `` element is required if the `@max-occurs` attribute has a value greater than '1' or is `unbounded`. This element provides additional information about how to handle the collection of data. + +The `group-as` element has the following set of attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@in-json`](#in-json) | `ARRAY`, `SINGLETON_OR_ARRAY`, or `BY_KEY` | optional | `SINGLETON_OR_ARRAY` | +| [`@in-xml`](#in-xml) | `GROUPED`, `UNGROUPED` | optional | `UNGROUPED` | +| [`@name`](#name) | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +##### `@in-json` + +The optional `@in-json` attribute controls the representational form of a group of instances in JSON and YAML. + +When no attribute and value is provided for the `@in-json` attribute, the value MUST default to `SINGLETON_OR_ARRAY`. + +One of the following behaviors MUST be used based on the provided, or default value when no attribute and value is provided. + +| Value | JSON and YAML Behavior | +|:--- |:--- | +| [`ARRAY`](#in-jsonarray) | The child value(s) MUST be represented as an array of values. | +| [`SINGLETON_OR_ARRAY`](#in-jsonsingleton_or_array) | If a single value is provided, then the child value MUST be that value; otherwise, for multiple values, the child values MUST be represented as an array of values. | +| [`BY_KEY`](#in-jsonby_key) | The child value MUST be an intermediate object based on the ``. + +###### `@in-json="ARRAY"` + +TODO: P2: complete this section. +###### `@in-json="SINGLETON_OR_ARRAY"` + +TODO: P2: complete this section. +###### `@in-json="BY_KEY"` + + +TODO: P2: Address issue https://github.com/usnistgov/metaschema/issues/316 + +##### `@in-xml` + +The optional `@in-xml` attribute controls the representational form of a group of instances in XML. + +When no attribute and value is provided for the `@in-xml` attribute, the value MUST default to `UNGROUPED`. + +One of the following behaviors MUST be used based on the provided, or default value when no attribute and value is provided. + +| Value | XML Behavior | +|:--- |:--- | +| [`GROUPED`](#in-xmlgrouped) | The child elements MUST be placed within a wrapper element with a local name equal to the value of the `@name` attribute. Each child element's local name will be the [effective name](#naming-and-use-name) of the instance. | +| [`UNGROUPED`](#in-xmlungrouped) | The child elements MUST appear without a grouping (wrapper) element. The `group-as/@name` is ignored. Each child element's local name will be the [effective name](#naming-and-use-name) of the instance. | + +###### `@in-xml="GROUPED"` + +TODO: P2: complete this section. + +###### `@in-xml="UNGROUPED"` + +TODO: P2: complete this section. + +##### `@name` + +The REQUIRED `@name` attribute declares the grouping name to use in JSON, YAML and XML (when exposed). + +In JSON and YAML, this name is used as the property name. + +In XML, the specific use of the `@name` is based on the `@in-xml` attribute's value. + +{{}} +While not required, use of a plural form of the [effective name](#naming-and-use-name) for the instance is a general convention applied to `` naming. +{{}} + +### Instance Naming + +Given the set of instance names for a *definition*, a given *instance* on that definition MUST have a unique effective name. If the instance allows a [maximum cardinality](#max-occurs) greater than `1`, the [``](#name) MUST also be unique within the set of *instance names* for the *definition*. + +For *field instance* values, the effective name of the value, based on a `` or `` MUST also be unique within the set of *instance names* for the *definition*. This ensures that the property name for the *field* value is unique in JSON and YAML. + +For *field instances* that use [`@in-xml="UNWRAPPED"`](#in-xml-1), no other effective instance name in the within the set of *instance names* for the *definition* MUST be named in a way that matches the allowed element contents of the [markup-multiline data type](/specification/datatypes/#markup-multiline) in XML. This ensures that a naming clash with markup data is disallowed. + +With these limitations, a model may be defined to contain any mix of fields and assemblies. + +{{}} +In JSON, YAML, and XML, the [effective names of named instances](#naming-and-use-name) and the [grouping name](#group-as) of named model instances need to be restricted to allow for distinct naming of resulting JSON and YAML properties, and XML elements. By ensuring that names are unique, Metaschema aware parsers are able to map data elements in JSON, YAML, and XML into Metaschema module based *instances*. +{{}} + +### `` Instance + +A *field instance* is used to declare that a top-level *field definition* is part of the model of an *assembly definition*. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@in-xml`](#in-xml-1) | `WRAPPED`,`WITH_WRAPPER` or `UNWRAPPED` | optional | `WRAPPED` | +| [`@max-occurs`](#max-occurs) | [`positive-integer`](/specification/datatypes/#non-negative-integer) or `unbounded` | optional | `1` | +| [`@min-occurs`](#min-occurs) | [`non-negative-integer`](/specification/datatypes/#non-negative-integer) | optional | `0` | +| [`@ref`](#ref) | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [``](#group-as) | special | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | + +The attributes and elements specific to a `` instance are described in the following subsections. The elements and attributes common to all named model instance types are [defined earlier](#common-named-model-instance-data) in this specification. + +The [`@ref`](#ref) attribute MUST reference a top-level *field definition's* [`@name`](/specification/syntax/definitions/#name) that is in scope. See [Definition Name Resolution](/specification/syntax/module/#definition-name-resolution) for a detailed explanation of definition name scoping. + +#### `@in-xml` + +TODO: P2: describe this with examples + +### `` Instance + +A `` instance is a special type of *field instance* that also declares a new single use, [inline *field definition*](/specification/syntax/inline-definitions/#inline-define-field). It combines a subset of the data used to declare a [*field definition*](/specification/syntax/definitions/#top-level-define-field) and a [*field instance*](#field-instance). + +The data model of the [inline `` instance](/specification/syntax/inline-definitions/#inline-define-field) is covered in the section of the specification discussing [inline definitions](/specification/syntax/inline-definitions/). + +### `` Instance + +An *assembly instance* is used to declare that a top-level *assembly definition* is part of the model of an *assembly definition*. + +Attributes: + +| Attribute | Data Type | Use | Default Value | +|:--- |:--- |:--- |:--- | +| [`@deprecated`](#deprecated-version) | version ([`string`](/specification/datatypes/#string)) | optional | *(no default)* | +| [`@max-occurs`](#max-occurs) | [`positive-integer`](/specification/datatypes/#non-negative-integer) or `unbounded` | optional | `1` | +| [`@min-occurs`](#min-occurs) | [`non-negative-integer`](/specification/datatypes/#non-negative-integer) | optional | `0` | +| [`@ref`](#ref) | [`token`](/specification/datatypes/#token) | required | *(no default)* | + +Elements: + +| Element | Data Type | Use | +|:--- |:--- |:--- | +| [``](#formal-name) | [`string`](/specification/datatypes/#string) | 0 or 1 | +| [``](#description) | [`markup-line`](/specification/datatypes/#markup-line) | 0 or 1 | +| [``](#prop) | special | 0 to ∞ | +| [``](#naming-and-use-name) | [`token`](/specification/datatypes/#token) | 0 or 1 | +| [``](#group-as) | special | 0 or 1 | +| [``](#remarks) | special | 0 or 1 | + +There are no attributes and elements specific to an `` instance. The elements and attributes common to all named model instance types are [defined earlier](#common-named-model-instance-data) in this specification. + +The [`@ref`](#ref) attribute MUST reference a top-level *assembly definition's* [`@name`](/specification/syntax/definitions/#name) that is in scope. See [Definition Name Resolution](/specification/syntax/module/#definition-name-resolution) for a detailed explanation of definition name scoping. + +### `` Instance + +A `` instance is a special type of *field instance* that also declares a new single use, [inline *assembly definition*](/specification/syntax/inline-definitions/#inline-define-assembly). It combines a subset of the data used to declare a [*assembly definition*](/specification/syntax/definitions/#top-level-define-field) and a [*assembly instance*](#assembly-instance). + +The data model of the [inline `` instance](/specification/syntax/inline-definitions/#inline-define-assembly) is covered in the section of the specification discussing [inline definitions](/specification/syntax/inline-definitions/). + +## Other Model Instance Types + +The elements [``](#choice-selections) and [``](#any) are specialized model instance types that have different semantics from the [name model instances](#named-model-instances) above. +### `` Selections + +Permits the mutually exclusive use of a non-empty set of [named model instances](#named-model-instances). + +- [``](#assembly-instance) - Instantiates a globally defined [assembly definition](/specification/syntax/definitions/#top-level-define-assembly) as a model instance. +- [``](#field-instance) - Instantiates a globally defined [field definition](/specification/syntax/definitions/#top-level-define-field) as a model instance. +- [``](/specification/syntax/inline-definitions/#inline-define-assembly) - Defines a [single use assembly](/specification/syntax/inline-definitions/#inline-define-assembly) for use as a model instance. +- [``](/specification/syntax/inline-definitions/#inline-define-field) - Defines a [single use field](/specification/syntax/inline-definitions/#inline-define-field) for use as a model instance. + +### `` + +TODO: P2: describe this with examples diff --git a/website/content/specification/syntax/module.md b/website/content/specification/syntax/module.md new file mode 100644 index 000000000..752c36bad --- /dev/null +++ b/website/content/specification/syntax/module.md @@ -0,0 +1,273 @@ +--- +title: "Metaschema Module" +linkTitle: "Module" +description: "Metaschema module syntax." +weight: 10 +--- + +# Metaschema Module + +A *Metaschema module* is represented using the top-level XML element ``. + +For example: + +```xml + + + Computer Model + 0.0.5 + computer + http://example.com/ns/computer + http://example.com/ns/computer + +

      This is an example model to describe the components of a computer.

      +

      The "computer" element is the root element of this model.

      +       + +       +``` + +Attributes: + +| Attribute | Data Type | Use | Default Value | Section | +|:--- |:--- |:--- |:--- |:--- | +| [`@abstract`](#abstract-modules) | `yes` or `no` | optional | `no` | Header: [Abstract Module](#abstract-modules) | + +Elements: + +| Element | Data Type | Use | Section | +|:--- |:--- |:--- |:--- | +| [``](#schema-name) | [`markup-line`](/specification/datatypes/#markup-line) | 1 | Header: [Documentation](#module-documentation) | +| [``](#schema-version) | version ([`string`](/specification/datatypes/#string)) | 1 | Header: [Documentation](#module-documentation) | +| [``](#short-name) | [`token`](/specification/datatypes/#token) | 1 | Header: [Documentation](#module-documentation) | +| [``](#xml-namespace) | [`uri`](/specification/datatypes/#uri) | 1 | Header: [XML Namespace](#xml-namespace) | +| [``](#json-base-uri) | [`uri`](/specification/datatypes/#uri) | 1 | Header: [JSON Base URI](#json-base-uri) | +| [``](#remarks) | special | 0 or 1 | Header: [Documentation](#module-documentation) | +| [``](#import) | special | 0 to ∞ | [Module Imports](#import) | +| [``](/specification/syntax/definitions/#top-level-define-assembly),
      [``](/specification/syntax/definitions/#top-level-define-field), and
      [``](/specification/syntax/definitions/#top-level-define-flag) | special | 0 to ∞ | [Module Definitions](/specification/syntax/definitions/) | + +The first set of elements in a *Metaschema module* represent the *header*, which contains information about the *Metaschema module* as a whole. The remainder of this section discusses the use of these elements. + +{{}} +**Note:** There is no explicit separation between the *header* and the *definitions* in a *Metaschema module*. The header ends where the [``](#import), [``](/specification/syntax/definitions/#top-level-define-assembly), [``](/specification/syntax/definitions/#top-level-define-field), and [``](/specification/syntax/definitions/#top-level-define-flag) elements first appear. +{{}} + +## Module Documentation + +Top-level documentation for the *Metaschema module* appears in the the *header* section. + +{{}} +The documentation within the *header* applies to the whole *Metaschema module*. Each child object *definition* will also have associated documentation that appears within that object's declaration. +{{}} + +The *header* may include the following elements, in order: + +## Abstract Modules + +The optional `@abstract` attribute indicates if the *Metaschema module* is intended to be used on its own or only for import into another *Metaschema module*. + +The following values describe the intent of `@abstract` attribute. + +- `no` - Indicates that the *Metaschema module* is usable on its own. This is the default behavior when `@abstract` is not declared. +- `yes` - Indicates that the *Metaschema module* is not usable on its own. Instead, the *Metaschema module* SHOULD only be *imported* by other Metaschema modules. + +{{}} +It's a best practice to mark *Metaschema modules* that are intended only for reuse in other *Metaschema modules* as `@abstract=yes`. This communicates to users of the module that the module is not standalone. +{{}} + +For example: + +```xml {linenos=table,hl_lines=[3]} + + + + +``` + +### `` + +The required `` is a line of [structured markup](/specification/datatypes/#markup-line) that provides a human-readable name, suitable for display, for the *information model* represented by this *Metaschema module*. + +For example: + +```xml +Computer Model +``` + +### `` + +A required, unique string literal value indicating the distinct version assigned to the *Metaschema module*. + +This version MUST provide a means to distinctly identify a given revision of the *Metaschema module* in a series of revisions. The value child of the `` SHOULD be a [semantic version](https://semver.org/), which allows for automatically determining if a given version precedes, matches, or succeeds another version. + +{{}} +Use of [semantic versioning](https://semver.org/), also referred to as "semver", in a `` is encouraged, since semver provides a standardized set of rules for how version numbers are assigned and incremented. This allows computation over version ranges and comparison of individual versions. +{{}} + +For example: + +```xml +0.0.5 +``` + +This example defines a semantic version with a major version of `0`, a minor version of `0`, and a patch version of `5`. + +### `` + +A required, unique string literal value that identifies a series of revisions of the *Metaschema module*. Each revision in the series will have the same ``. + +For example: + +```xml +computer +``` + +Together, the `` and `` provide an identification pair that uniquely identifies a given *Metaschema module* revision. This pair of values is intended to be associated with any schemas, code, tools, or other derivative artifacts produced from the *Metaschema module*, providing for clear identification of the revision from which an artifact is derived. + +### `` + +An optional sequence of [multiline markup](/specification/datatypes/#markup-multiline) used to provide additional supporting notes related to the *Metaschema module*. + +A `` element is typically used to include explanatory commentary of any kind. + +For example: + +```xml + +

      This is an example model to describe the components of a computer.

      +

      The "computer" element is the root element of this model.

      +       +``` + +{{}} +As a general purpose element, the `` element is also permitted to appear elsewhere in the *Metaschema module* model. Its scope of application is tied to the location of use in the document. Thus, the top-level remarks relate to the entire *Metaschema module*, while remarks on a *definition* relate to the *definition*. +{{}} + +## XML `` + +The required `` element is a [uniform resource identifier](https://www.rfc-editor.org/rfc/rfc3986) (URI) that identifies the [XML Namespace](https://www.w3.org/TR/xml-names/#sec-namespaces) to use for XML instances of the model. + +All *information elements* defined in the *Metaschema module* will be assigned to this namespace when handling related XML data. + +{{}} +Note: *Information elements* defined in an [imported *Metaschema module*](#import), will be assigned the namespace declared in that module's header. This makes it possible to use and differentiate *information elements* defined with different namespaces. +{{}} + +The XML namespace defined using this element will be the target namespace used in an XML schema generated from this *Metaschema module*. + +## `` + +The required `` element is a [uniform resource identifier](https://www.rfc-editor.org/rfc/rfc3986) (URI) that identifies the URI used in the [`$schema` keyword](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-01#section-7) in JSON Schemas generated from this *Metaschema module*. + +## `` + +The `` element is used to import the definitions defined in another Metaschema module for use in the importing Metaschema module. + +An import cycle occurs when a *Metaschema module* imports itself directly or transitively. + +An example scenario is illustrated below. + +```mermaid +graph TB + moduleA -- imports --> moduleB + moduleB -- imports --> moduleA +``` + +In this example a cycle is created `A -> B -> A`. + +When processing imports, an implementation MUST be capable of detecting and generating a fatal error when an import cycle is found. + +## Definition Name Resolution + +The [top-level *definition* names](/specification/syntax/definitions/#name) exported by a *Metaschema module* are controlled by the top-level *definition's* [`@scope`](/specification/syntax/definitions/#scope) attribute. Definitions with a given *Metaschema module* without an explicit `@scope` or with `@scope="global"` are exported for use by other *Metaschema modules* that import it directly or transitively. The possibility of name conflicts arises when two modules have different definitions of the same type (i.e. flag, field, assembly) with the same name, and these modules are both imported. + +The following rules MUST be applied to resolve naming conflicts that arise from [module imports](#import). + +1. A *definition* MUST be considered for import if the *definition* is in an [imported module](#import), and it either has no [`@scope`](/specification/syntax/definitions/#scope) or `@scope="global"`. A *definition* with `@scope="local"` MUST be ignored. +1. When a *definition* of a given type is imported, if its name matches the name of a previously imported *definition* of the same type, the most recently imported *definition* MUST be used. +1. If a *definition* of a given type exists in the importing *Metaschema module* that matches the name of a previously imported *definition* of the same type, the definition in the importing *Metaschema module* MUST be used. +1. Each module uses the resulting set of named *definitions* to resolve references within the module. + +The following example illustrates how scoping affects definition name resolution. + +The following file is the `shadow-imported_metaschema.xml`. +```xml {linenos=table,hl_lines=[8,12,"20-24"]} + + + Imported Metaschema + 1.0 + imported + http://csrc.nist.gov/ns/metaschema/example/1.0 + + + Assembly that includes global and local flags + This assembly references a global flag that is shadowed by a global flag defined + in the importing metaschema module. + + +

      This reference should be to the globally scoped flag "global-flag" from the imported + metaschema module.

      +       +       +       + + + Global Flag - Imported Metaschema + A flag from the imported metaschema. Its scope is global and it's shadowed by the + definition with the same name in the importing metaschema module. + +       +``` + +This file declares the globally scoped *assembly definition* named `imported-flags` (on line 8), which references the global scoped *flag definition* `global-flag` (on line 12). It also declares the globally scoped *flag definition* named `global-flag` (on line 20). + +The following file is the `shadow-importing_metaschema.xml`. +```xml {linenos=table,hl_lines=[8,10,15,"32-35"]} + + + Importing Metaschema + 1.0 + importing + http://csrc.nist.gov/ns/metaschema/example/1.0 + + + + + Assembly that global flags + This assembly references a global flag that shadows a global flag defined in an + imported metaschema module. + including-flags + + +

      This reference is to the globally scoped flag "global-flag" from the importing + metaschema. This definition is taking precedence over the other definition imported + (with the same name).

      +       +       + + + +

      This is the imported "imported-flags" assembly, complete with its full model + from the imported metaschema module, including the global-flag defined there.

      +       +       +       +       + + + Global Flag - Importing Metaschema + A flag from the importing metaschema. Its scope is global. This should be marked + as a shadowing of another imported flag. + +       +``` + +This file imports the `shadow-imported_metaschema.xml` (on line 8). It also declares a global scoped *assembly definition* named `importing-A` (on line 10), which references the *flag definition* `global-flag` (on line 15). It also declares the globally scoped *flag definition* named `global-flag` (on line 32). + +Both files contain globally scoped *flag definitions* named `global-flag`. + +According to the rules above, the following is true. + +- The assembly named `imported-flags` uses the flag named `global-flag` from the `shadow-imported_metaschema.xml`. This is because definitions names are resolved in the local context of each model. +- The assembly named `importing-A` uses the flag named `global-flag` from the `shadow-importing_metaschema.xml`. This is because definitions declared in the current module shadow imported definitions. diff --git a/website/content/tutorials/1-getting-started/_index.md b/website/content/tutorials/1-getting-started/_index.md index 13ba3fb06..04df52499 100644 --- a/website/content/tutorials/1-getting-started/_index.md +++ b/website/content/tutorials/1-getting-started/_index.md @@ -1,42 +1,43 @@ --- title: "Getting Started with Metaschema" -Description: "" -heading: Getting Started with Metaschema -toc: - enabled: true +description: "" --- -## Understanding the Domain and Designing the Model +# Getting Started with Metaschema Metaschema is a framework for consistently organizing information into machine-readable data formats. For example, if we want to build tools to exchange information about computers, how do we represent a computer in a data format? How do we design it to be consistent and reusable across different software? How do we benefit from the right amount of structured information about computers in that format? -To start organizing this information consistently, we need to consider our mental model of what a computer is. We have to think of the different parts of a computer, sub-parts, and how to compose those parts into a whole. Let's consider a computer such as one visualized below. +## Understanding the Domain and Designing the Model + +To start organizing this computer information consistently, we need to consider our mental model of what a computer is. We have to think of the different parts of a computer, sub-parts, and how to compose those parts into a whole. Let's consider a computer such as one visualized below. !["Exploded view of a personal computer, unlabeled" from Wikipedia, as created by Gustavb, and published under the Creative Commons Attribution-Share Alike 3.0 Unported license](/img/computer.svg) Source: [Wikipedia](https://commons.wikimedia.org/wiki/File:Personal_computer,_exploded_5,_unlabeled.svg) -In Metaschema terms, this design process is making an [information model](/specification/concepts/terminology/#information-model) for a [managed object](/specification/concepts/terminology/#managed-object), the computer, into [a data model](/specification/concepts/terminology/#data-model) within the [domain](/specification/concepts/terminology/#domain) of computing. And once we understand the required information structure for the computer in this domain, how do we specify a model in Metaschema and what are the benefits? +Based on this picture, the knowledge [domain](/specification/glossary/#domain) we want to describe is information about the components of a personal computer. We need to design an [information model](/specification/glossary/#information-model) that can sufficiently describe the necessary information in this domain. At the core of this information model, we have the concept of a personal computer, which represents the root [information element](/specification/glossary/#information-element) of the information model. Our design process will focus around this domain, developing an information model focused on the personal computer and all related information elements that describe the parts and sub-parts of a computer. -## Metaschema Concepts +We then want to represent this computer information model in one or more concrete data models that are aligned with commonly used data formats like JSON, XML, and YAML. -Metaschema helps developers to define models once, in a Metaschema definition. The definition specifies the model of information for the managed object in supported machine-readable data formats. A document in such a format is an instance of that definition. A schema can be used to check the instance is well-formed and valid against the definition's specification. Such schemas can be derived deterministically and programmatically from a Metaschema definition (or "metaschema"). +Once we understand the required information structure for a computer, how do we specify a model in Metaschema and what are the benefits of using a Metaschema-based approach to move towards a set of equivalent data models? -{{}} +## Metaschema Concepts + +Metaschema helps developers to define information models once as a [Metaschema module](../../specification/glossary/#metaschema-module). A Metaschema module specifies the information elements of the information model and how that model is represented in supported machine-readable data formats (i.e. JSON, YAML, XML), which we call a [data model](/specification/glossary/#data-model). A document in such a format is an instance of that module. A schema can be used to check that a document is well-formed and valid against the model represented by the format. Such schemas can be derived deterministically and programmatically from a Metaschema module (or "metaschema"). +```mermaid erDiagram - "Metaschema definition" }|..|{ "instance" : "must specify model of" - "Metaschema tool" }|..|{ "Metaschema definition" : "must parse" - "Metaschema tool" }|..|{ "instance" : "can parse" + "Metaschema module" }|..|{ "document instance" : "must specify model of" + "Metaschema tool" }|..|{ "Metaschema module" : "must parse" + "Metaschema tool" }|..|{ "document instance" : "can parse" "Metaschema tool" }|..|{ "schema" : "can generate" - "schema" }|..|{ "instance" : "must validate" - -{{}} + "schema" }|..|{ "document instance" : "must validate" +``` -## Basic Modeling and Basic Metaschema Defintions +## Basic Modeling and Basic Metaschema Module -We start with an empty Metaschema definition, like the one below, saved in a file called `computer_metaschema.xml`. +We start with an empty Metaschema module, like the one below, saved in a file called `computer_metaschema.xml`. ```xml @@ -44,9 +45,9 @@ We start with an empty Metaschema definition, like the one below, saved in a fil       ``` -Metschema definitions, like the one above, are in XML. A definition begins and ends with capitalized `METASCHEMA` tags. This definition is an empty file, and it is not a valid, well-formed defintion. It is simply the base we will start with. Within those beginning and ending tags, we want to add useful metadata for both developers and Metaschema-enabled tools to consume this definition, as below. +Metaschema modules, like the one above, are expressed in XML. A module begins and ends with capitalized `METASCHEMA` tags. This module is an empty file, which means it is not a valid, well-formed module, since it lacks any of the required data elements. It is simply the base we will start with. Within the beginning and ending tags, we want to add the required and useful metadata needed for both developers and Metaschema-enabled tools to consume this module. We do this below. -```xml +```xml {linenos=table,hl_lines=["3-7"]} Computer Model @@ -58,13 +59,15 @@ Metschema definitions, like the one above, are in XML. A definition begins and e ``` -The metadata above provides useful information to us Metaschema developers and our tools that parse Metaschema definitions. The `schema-name` is the long-form, descriptive name of the computer model. The `schema-version` is to give the model itself a version number, for either developers or their tools to use. The `short-name` is the shortened form of the `schema-name`. Normally, Metaschema-enabled tools will parse or generate data with this name `computer`, not `Computer Model`. The `namespace` is a URI used to identify the model and its parts as belonging to a single scope for XML data and schemas. Similarly, the `json-base-uri` serves a similar purpose for JSON data and schemas. +The metadata above provides the useful information needed by us: Metaschema developers and our tools that parse Metaschema modules. The `` is the long-form, descriptive name of the computer model. The `` gives the model itself a version number signifying the iterative instance of the model, for both developers or their tools to use. The `` is the shortened form of the `schema-name`, which provides a human-readable identifier for the model. Normally, Metaschema-enabled tools will parse or generate data with this name `computer`, not `Computer Model`. The `namespace` is a URI used to identify the model and its parts as belonging to a single scope for XML data and schemas. Similarly, the `json-base-uri` serves a similar purpose for JSON and YAML data, and JSON schemas. -It is important to note this definition is just a starting point. This definition is the most minimally viable definition possible: it is well-formed and valid against [the XML Schema for the Metaschema syntax itself](), but our Metaschema-enabled tools should consider this an empty definition. We have not yet declared a `root-name` and there is no data model yet, so let's start one. We will begin by designing a computer object to have just an identifier. +It is important to note this module is just a starting point. This module is the most minimally viable module possible: it is well-formed and valid against [the XML Schema for the Metaschema syntax itself](https://github.com/usnistgov/metaschema/blob/develop/schema/xml/metaschema.xsd), but Metaschema-enabled tools should consider this an empty module, since we have not yet declared a complete implementation of an information element yet. -We will now add to the [`assembly`](/specification/concepts/terminology/#assembly) for a computer itself and give it an identifier `flag`. +So let's start defining the "computer" information element. We will begin by designing a computer object to have just an identifier. -```xml +We will add an `id` flag, that represents the computer's identifier, to the `` definition named `computer`. + +```xml {linenos=table,hl_lines=["9-17"]} Computer Model @@ -74,19 +77,27 @@ We will now add to the [`assembly`](/specification/concepts/terminology/#assembl http://example.com/ns/computer Computer Assembly - A container object for a computer, its parts, and its sub-parts. + A container object for a computer, its parts, and its + sub-parts. computer Computer Identifier - An identifier for classifying a unique make and model of computer. + An identifier for classifying a unique make and model of + computer. ``` -With the definition of the first `assembly` our Metaschema definition takes shape. Firstly, we now add the `root-name` element to identify for Metaschema-enabled tools this `assembly`, whether there are one or more top-level ones defined, is the root element of our data models. This will come in handy later. In the `assembly` declaration, we have defined a `computer` that must have an `id`, the value of which must be `string`. With Metaschema-enabled tooling, we can have information about a computer like below in their respective JSON, XML, and YAML data formats. +With the definition of the first ``, representing a simple computer information element, our Metaschema module starts to take shape. + +In the `` declaration we have defined an object named `computer` (see line 8). -An instance for the model above is below in JSON, XML, and YAML data formats. +The computer object must have an `id`, the value of which must be [`string`](/specification/datatypes/#string) (see lines 12-15). + +The `` element is used to identify to Metaschema-enabled tools that this assembly must be the root element of our data model (see line 11). This will come in handy later. + +With Metaschema-enabled tooling, we can now represent information about a computer in the respective JSON, XML, and YAML data formats. The following are equivalent content examples for the model above using JSON, XML, and YAML. {{< tabs JSON XML YAML >}} {{% tab %}} @@ -113,20 +124,21 @@ computer: {{% /tab %}} {{< /tabs >}} - -At this point, we have our first functional and complete Metaschema definition. When we write Metaschema-enabled tools, they ought to be able to parse this definition and use it to parse one or more instances in JSON, XML, or YAML, as specified in that definition. All three instances above are to be equivalent. +At this point, we have our first functional and complete Metaschema definition and some basic content instance examples that are aligned with the model we have designed so far. Metaschema-enabled tools ought to be able to parse this module and use it to parse the content instances immediately above, as specified based on this module. ## Assemblies, Fields, and Flags -It is important to have a computer with an identifier, but our stakeholders want far more. We can add `field`s and `flag`s for simple key-value properties on a computer and assemblies for more complex objects. We need to continue our design work to understand and specify our information and data models with Metaschema, so we return to modeling once again. +It is important to have a computer with an identifier, but our stakeholders want far more. Using metaschema, we can add a `field` or `flag` for simple key-value properties on a computer, and an `assembly` for more complex objects. + +To explore and understand these concepts, we need to continue our design work on the computer model. We return to modeling once again. -Let's return to the diagram of the computer before, but now consider how we model the parts of a computer, the sub-parts, and their relationships. Our stakeholders provided us this diagram, and these are the key data points they need our software to process and store. +Let's return to the diagram of the computer from before, but now consider how we might model the parts of a computer, the sub-parts, and their relationships. Our stakeholders provided us this diagram, and these are the key data points they need our software to process and store. !["Exploded view of a personal computer" from Wikipedia, as created by Gustavb, and published under the Creative Commons Attribution-Share Alike 3.0 Unported license](/img/computer_numbered.svg) Source: [Wikipedia](https://upload.wikimedia.org/wikipedia/commons/1/13/Personal_computer%2C_exploded_4.svg) -Below are the parts and sub-parts we want in our information model of a computer in that diagram that our stakeholders require. +Below are the parts and sub-parts our stakeholders want in our information model of a computer based on the diagram. 1. Display 1. Motherboard @@ -140,7 +152,7 @@ Below are the parts and sub-parts we want in our information model of a computer 1. Keyboard 1. Mouse -When we consider the parts and sub-parts, we recognize some hierarchical relationships that we arrange into outline form. +When we consider the parts and sub-parts, we recognize some hierarchical relationships, represented below in outline form. - Display - Motherboard @@ -154,7 +166,7 @@ When we consider the parts and sub-parts, we recognize some hierarchical relatio - Keyboard - Mouse -After discussion with stakeholders of these new data formats, the different stakeholders agree we need to structure additional information about computers, parts, and sub-parts as well. +After discussion with our stakeholders, there is agreement we need to structure additional information about computers, parts, and sub-parts as well. - **Computer** - **Vendor information:** incorporation name; office address; product website @@ -170,11 +182,13 @@ After discussion with stakeholders of these new data formats, the different stak - **Keyboard:** product name; type - **Mouse:** product name; type -With this outline, we acknowledge there is a hierarchy, and it is important to how we design the managed objects of a computer, especially the motherboard. How can we use Metaschema to encode these hierarchies across data formats? We use assemblies, and within those assemblies, fields and flags in a particular order. +With this outline, we acknowledge the need for a hierarchy, which will impact how we design the managed objects of a computer, especially the motherboard. -With an `assembly`, we can specify a complex named object, not just a simple key-value pair. We can annotate this complex named object itself with `flag`s. The object we specify in the assembly can have optional key-values, which we define with `field`s. With these Metaschema concepts, we can enhance the `computer` model to include an `assembly` for a motherboard and include its sub-parts like so. +How can we use Metaschema to encode these hierarchies across data formats? We use assemblies, and within those assemblies, fields and flags in a particular order. -```xml +With an `assembly`, we can specify a complex named object, not just a simple key-value pair. We can annotate this complex named object itself with `flag`s. The object we specify in the assembly can have optional key-values, which we define with `field`s. Using these Metaschema concepts, we can enhance the `computer` model to include an `assembly` for a motherboard and include its sub-parts like so. + +```xml {linenos=table,hl_lines=["16-113"]} Computer Model @@ -207,7 +221,7 @@ With an `assembly`, we can specify a complex named object, not just a simple key Vendor Address The physical address of an office location for the vendor.       - + Vendor Website A public website made by the vendor documenting their parts as used in the computer. @@ -266,7 +280,7 @@ With an `assembly`, we can specify a complex named object, not just a simple key Product Name The product name from the vendor of the computer part. - + Memory Module Size Size of the memory module in binary, not SI base-10 units, meaning a kilobyte is 1024 bytes, not 1000 bytes. @@ -294,9 +308,9 @@ With an `assembly`, we can specify a complex named object, not just a simple key ``` -We now have a nested motherboard `assembly` in a computer `assembly` with assorted `flag`s and `field`s to present the important hierarchy of information in the motherboard. With a more detailed model, we can have our Metaschema-enabled tools parse or generate instances. +We now have a nested `motherboard` assembly in a `computer` assembly with assorted flags and fields to present the important hierarchy of information related to the motherboard. With this more detailed model, we can have our Metaschema-enabled tools parse or generate content instances. -An instance for the model above is below in JSON, XML, and YAML data formats. +The following are example content instances for the model above in JSON, XML, and YAML data formats. {{< tabs JSON XML YAML >}} {{% tab %}} @@ -399,23 +413,25 @@ computer: {{% /tab %}} {{< /tabs >}} -With the expressive power of assemblies, flags, and fields, we can specify complex managed objects and control the structure of the intended information model in the resulting data formats. +With the expressive power of flags, fields, and assemblies, we can specify complex managed objects that implement the information elements of the intended information model. We can also use this expressive power to control the structure of the information in the resulting data formats. -Our Metaschema-enabled tools can parse and generate the different data formats. We specify flags on the `computer` assembly, but all else we define in the `model` of the `assembly`. And within that model, we can define the motherboard `assembly` inline with its own `flag` and `model`. These abstract definitions, along with information we provide with them such as names of groups, enables a Metaschema-enabled tool to sort out and distinguish the data points as we wish them to appear differently in a different syntax. A JSON schema can describe a JSON format that is idiomatic in JSON, while an XML Schema can do the same in XML with the same Metaschema model. As this example demonstrates, Metaschema allows developers to render the data independent of the notation used to represent it, and convert into any other notation their tools to support. +Our Metaschema-enabled tools can parse and generate the different data formats based on this single `computer` Metaschema module. We specify flags on the `computer` assembly, but all else we define in the `` of the ``. And within that model, we can define the `motherboard` assembly inline with its own flags and model. These abstract definitions, along with information we provide with them, such as names of groups, enables a Metaschema-enabled tool to sort out and distinguish the data points as we wish them to appear in each supported data model. A JSON schema can describe a JSON format that is idiomatic in JSON, while an XML Schema can do the same in XML with the same Metaschema model. As this example demonstrates, Metaschema allows developers to render the data independent of the notation used to represent it, and convert into any other notation their tools to support. -We define the data types for different Metaschema fields and flags. Our Metaschema-enabled tools can leverage pre-compiled schemas or generate their own to enforce `field` and `flag` values that are valid for their type. For example, our Metaschema-enabled tools should accept a valid URI for the `website` field of the vendor `assembly`, but not any arbitrary string. For `byte-size`, they should only accept positive integer values greater than 0, not a decimal point number or string. Metaschema facilitates consistent enforcement of data typing so we developers do not have to. +We define the data types for different Metaschema fields and flags. Our Metaschema-enabled tools can leverage [pre-compiled schemas](/specification/datatypes/#data-type-schema-representations) or generate their own to enforce field and flag values that are valid for their type. For example, our Metaschema-enabled tools should accept a valid URI for the `website` field of the `vendor` assembly, but not any arbitrary string. This is accomplished using the [`uri`](/specification/datatypes/#uri) data type. For `byte-size`, they should only accept positive integer values greater than 0, not a decimal point number or string, based on the [`positive-integer`](/specification/datatypes/#positive-integer) data type. Metaschema facilitates consistent enforcement of data typing so we developers do not have to. -We also define the minimum and maximum number of elements for the different assemblies, flags, and field with `min-occurs` and `max-occurs` declarations. In our example, we have an optional `expansion-card` field in the motherboard `assembly`. Our Metaschema-enabled tools will parse or generate instances as valid with optional fields missing. On the other hand, a motherboard `assembly` missing the CPU `field` should throw errors, as should parsing or generating instances with one that one CPU `field` in the JSON, XML, or YAML format. +We also define the minimum and maximum number of elements for the different assemblies, flags, and field with `@min-occurs` and `@max-occurs` declarations. In our example, we have an optional `expansion-card` field in the `motherboard` assembly. Our Metaschema-enabled tools will parse or generate instances as valid with optional fields missing. On the other hand, a `motherboard` assembly missing the `cpu` field should throw errors, as should parsing or generating instances with one that one `cpu` field in the JSON, XML, or YAML formats. ## Refactoring Metaschema Definitions and Deduplicating Code -We now have a robust information model for a computer we can express in JSON, XML, and YAML data models. But what if we want to enhance the information model? Can we add more information but also refactor to be more expressive while reducing redundancy? With Metaschema, yes we can. +We now have a robust information model for a computer we can express in JSON, XML, and YAML formats. But what if we want to enhance the information model? Can we add more information but also refactor the Metaschema module to be more expressive while reducing redundancy? With Metaschema, yes we can. -Our stakeholders determine supply chain information is very important. We need to know vendor information for all the different parts of the computer, specifically a company name and where the company is headquartered. This information should be maintained for not just the computer, but all parts and sub-parts. How can we add this to the Metaschema definition? +Our stakeholders determine supply chain information is very important to them. We need to express vendor information for all the different parts of the computer, specifically a company name and where the company is headquartered. This information should be maintained for not just the `computer` information element, but also for all parts and sub-parts. -For now, we can copy-paste vendor `assembly` into all relevent assemblies, not just the top-level computer assembly. +How can we add this to the Metaschema module? -```xml +For now, we can copy-paste the `vendor` assembly into all relevant assemblies, not just the top-level `computer` assembly. + +```xml {linenos=table,hl_lines=["43-64","77-98","117-138","154-175","191-212"]} Computer Model @@ -448,7 +464,7 @@ For now, we can copy-paste vendor `assembly` into all relevent assemblies, not j Vendor Address The physical address of an office location for the vendor. - + Vendor Website A public website made by the vendor documenting their parts as used in the computer. @@ -474,7 +490,7 @@ For now, we can copy-paste vendor `assembly` into all relevent assemblies, not j Vendor Address The physical address of an office location for the vendor. - + Vendor Website A public website made by the vendor documenting their parts as used in the computer. @@ -508,7 +524,7 @@ For now, we can copy-paste vendor `assembly` into all relevent assemblies, not j Vendor Address The physical address of an office location for the vendor. - + Vendor Website A public website made by the vendor documenting their parts as used in the computer. @@ -548,7 +564,7 @@ For now, we can copy-paste vendor `assembly` into all relevent assemblies, not j Vendor Address The physical address of an office location for the vendor. - + Vendor Website A public website made by the vendor documenting their parts as used in the computer. @@ -585,7 +601,7 @@ For now, we can copy-paste vendor `assembly` into all relevent assemblies, not j Vendor Address The physical address of an office location for the vendor. - + Vendor Website A public website made by the vendor documenting their parts as used in the computer. @@ -595,7 +611,7 @@ For now, we can copy-paste vendor `assembly` into all relevent assemblies, not j Product Name The product name from the vendor of the computer part. - + Memory Module Size Size of the memory module in binary, not SI base-10 units, meaning a kilobyte is 1024 bytes, not 1000 bytes. @@ -622,7 +638,7 @@ For now, we can copy-paste vendor `assembly` into all relevent assemblies, not j Vendor Address The physical address of an office location for the vendor. - + Vendor Website A public website made by the vendor documenting their parts as used in the computer. @@ -645,7 +661,7 @@ For now, we can copy-paste vendor `assembly` into all relevent assemblies, not j ``` -An instance for the model above is below in JSON, XML, and YAML data formats. +Example content instances for the model above follow in JSON, XML, and YAML data formats. {{< tabs JSON XML YAML >}} {{% tab %}} @@ -828,10 +844,9 @@ computer: {{% /tab %}} {{< /tabs >}} +At this point we have updated our model to meet stakeholder needs, but the model itself is significantly more verbose. Fortunately, we can use Metaschema syntax to define an assembly, field, or flag once and reuse the definition elsewhere by reference with the `@ref` keyword. We can refactor our definition and do this with the `vendor` assembly and `product-name` field in the module below. -We have updated our model to meet stakeholder needs, but the model itself is significantly more verbse. Fortunately, we can use Metaschema syntax to define an `assembly`, `field`, or `flag` once and reuse the definition elsewhere by references with `ref` keyword. We can refactor our definition and do this with the vendor `assembly` and product name `field` in the definition below. - -```xml +```xml {linenos=table,hl_lines=["8-29","30-33",47,"56-57","72-73","85-86","98-99"]} Computer Model @@ -855,13 +870,13 @@ We have updated our model to meet stakeholder needs, but the model itself is sig Vendor Address The physical address of an office location for the vendor. - + Vendor Website A public website made by the vendor documenting their parts as used in the computer.       - + Product Name The product name from the vendor of the computer part. @@ -888,7 +903,7 @@ We have updated our model to meet stakeholder needs, but the model itself is sig The model number of the CPU on the motherboard of a computer. - + CPU Architecture The Instruction Set Architecture (ISA) of the processor, x86, x86-64, arm, or an alternative. @@ -904,7 +919,7 @@ We have updated our model to meet stakeholder needs, but the model itself is sig The model number of ATA socket on the motherboard of a computer. There will only be one socket on any motherboard. - + ATA Socket Type The type of ATA socket on the motherboard , pata (parallel ATA), sata (Serial ATA), or an alternative. @@ -917,8 +932,8 @@ We have updated our model to meet stakeholder needs, but the model itself is sig - - + + Memory Module Size Size of the memory module in binary, not SI base-10 units, meaning a kilobyte is 1024 bytes, not 1000 bytes. @@ -930,10 +945,7 @@ We have updated our model to meet stakeholder needs, but the model itself is sig - - Product Name - The product name from the vendor of the computer part. - + Expansion Card Type The type of expansion card on a motherboard of a computer, such as pci (PCI, e.g. Peripheral Component Interconnect), pcie (PCI Express), or an alternative. @@ -947,8 +959,8 @@ We have updated our model to meet stakeholder needs, but the model itself is sig ``` -We lifted the `assembly` definition for vendor and the definition of the product name `field` to outside the computer `assembly`. Because we have a `root-name` previously defined for the computer `assembly`, Metaschema-enabled tools will work just as before, generating and parsing the same instances with the computer `assembly` as the root, even with multiple top-level elements defined. At the same time, we reduced repeat copy-pasted code, and we can continue to add other requirements from our stakeholders and reuse their definitions across different elements of the model and maintain the original definition once. +In the example above, we lifted the assembly definition for `vendor` and the definition of the `product-name` field to outside the `computer` assembly. Because we have a `` previously defined for the `computer` assembly, Metaschema-enabled tools will work just as before, generating and parsing the same instances with the `computer` assembly as the root, even with multiple top-level elements defined. At the same time, we reduced repeated code, and we can continue to add other requirements from our stakeholders and reuse their definitions across different elements of the model, while maintaining the original definition once. As a result, this refactored model should be much easier to maintain over time. ## Conclusion -In this tutorial, we examined an example of a real-world object in a domain and how we would model it with a community of stakeholders. We created and incrementally improved a Metaschema definition, using it to our advantage for refactoring and modification. In doing so, we learned key Metaschema concepts and their benefits in application. Learning and applying these concepts will prepare us to explore more advanced topics in the following tutorials. +In this tutorial, we examined an example of a real-world information model in a domain and how we would model it with a community of stakeholders. We created and incrementally improved a Metaschema module, using Metaschema to our advantage for refactoring and modification. In doing so, we learned key Metaschema concepts and their benefits in application. Learning and applying these concepts will prepare us to explore more advanced topics in the following tutorials. diff --git a/website/content/tutorials/_index.md b/website/content/tutorials/_index.md index ae405c5dd..eddf34eee 100644 --- a/website/content/tutorials/_index.md +++ b/website/content/tutorials/_index.md @@ -1,11 +1,14 @@ --- title: "Metaschema Tutorials" -Description: "Collection of Metaschema tutorials" -heading: Getting Started with Metaschema +description: "Collection of Metaschema tutorials" menu: primary: name: Tutorials weight: 10 --- +# Tutorials + The following tutorials provide walk-throughs for developers to understand Metaschema, its use cases, and how to use or develop news to exercise them. + +- [Getting Started with Metaschema](1-getting-started/): Introduces the basics of Metaschema-based modeling using a "computer" model as an example. \ No newline at end of file diff --git a/website/content/use/_index.md b/website/content/use/_index.md index 22ade7ada..8d966bcb0 100644 --- a/website/content/use/_index.md +++ b/website/content/use/_index.md @@ -1,13 +1,29 @@ --- -title: "Using the Metaschema" -Description: "" -heading: Using the Metaschema +title: "Using the Metaschema Framework" +linkTitle: "Using Metaschema" menu: primary: name: Using weight: 10 --- -Currently, the Metaschema syntax uses an [XML-based format](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema.xsd). Alternate formats (e.g., JSON, YAML) are currently being considered. +# Using the Metaschema Information Modeling Framework -An [ISO Schematron](http://schematron.com/) ruleset is also [provided](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema-composition-check.sch) to enforce some of the rules described below. +Currently, a Metaschema [module](/specification/glossary/#metaschema-module) is defined using an [XML-based format](https://github.com/usnistgov/metaschema/blob/develop/schema/xml/metaschema.xsd). Alternate formats (e.g., JSON, YAML) are currently being considered. + +An [ISO Schematron](https://schematron.com/) ruleset is also [provided](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema-composition-check.sch) to enforce some of the rules described in the Metaschema [specification](/specification/). + +A [tutorial](/tutorials/1-getting-started/) covering basic concepts is provided that will walk you through an example of creating a new Metaschema module. + +## Schema Generation + +A Metaschema module can be used to generate a schema, expressed as an XML or JSON Schema, for the corresponding [*data model*](/specification/glossary/#data-model) in a format-specific, serializable form (e.g., XML, JSON, YAML). These generated schemas can be used to *validate* that data to be processed by the system is well-formed and consistent with the requirements of the data model. + +## Other Generative Use Cases + +Metaschema modules are used to generate other model-related artifacts based on the metaschema description. These artifacts include: + +- Conversion utilities that can convert content instances between the XML and JSON formats derived from a given metaschema definition, ensuring the resulting content is schema-valid, model-identical, and equivalent to its input (without loss or addition when processed in a Metaschema-aware context). +- Model-aware utilities and mock datasets for generic display, data conversion, reformatting, and testing. +- XML and JSON model documentation for use on a website (e.g., the [OSCAL website](https://pages.nist.gov/OSCAL/documentation/schema/)). +- Programming language APIs used for parsing data conformant to a given data model into a set of language-specific objects, and also writing data in language-specific objects out to one of the supported data model formats. diff --git a/website/layouts/partials/foot.html b/website/layouts/partials/foot.html deleted file mode 100644 index f408b2708..000000000 --- a/website/layouts/partials/foot.html +++ /dev/null @@ -1,7 +0,0 @@ - - diff --git a/website/layouts/partials/head.html b/website/layouts/partials/head.html deleted file mode 100644 index 3eeaf6c63..000000000 --- a/website/layouts/partials/head.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - - - - - - - - - - diff --git a/website/static/css/element-map.css b/website/static/css/element-map.css new file mode 100644 index 000000000..b3bbaab94 --- /dev/null +++ b/website/static/css/element-map.css @@ -0,0 +1,11 @@ +.highlight .element .element { + margin-left: 1rem; +} + +.highlight .element .attribute { + margin-left: 2rem; +} + +.highlight a { + color: inherit; +} diff --git a/website/static/img/oscal-gears-icon-140.png b/website/static/img/oscal-gears-icon-140.png deleted file mode 100644 index e69de29bb..000000000 diff --git a/website/static/img/oscal-gears-icon-32.png b/website/static/img/oscal-gears-icon-32.png deleted file mode 100644 index e69de29bb..000000000 diff --git a/website/static/img/oscal-page-icon-180.png b/website/static/img/oscal-page-icon-180.png deleted file mode 100644 index e69de29bb..000000000 diff --git a/website/themes/uswds b/website/themes/uswds index ac7915f3f..cc57ce2e1 160000 --- a/website/themes/uswds +++ b/website/themes/uswds @@ -1 +1 @@ -Subproject commit ac7915f3fa4d14fde6115b4a88634f46955a8c20 +Subproject commit cc57ce2e1efa8602d13160e98090bcacc8e6af93 diff --git a/website/themes/uswds-nist/assets/scss/_hugo-uswds-custom-styles.scss b/website/themes/uswds-nist/assets/scss/_hugo-uswds-custom-styles.scss new file mode 100644 index 000000000..71ae8e02e --- /dev/null +++ b/website/themes/uswds-nist/assets/scss/_hugo-uswds-custom-styles.scss @@ -0,0 +1,28 @@ +/* +---------------------------------------- +Hugo Module Styles +---------------------------------------- +!! Copy this file to your module. +---------------------------------------- +Custom module SASS goes here. + +i.e. +@include u-padding-right('05'); +---------------------------------------- +*/ + +@use "uswds-core" as *; + +.nist-footer { + font-family: inherit; +} + +#ln-messageHolder { + z-index: 1000; +} + +@media print { + #nistheadergoeshere, #nistfootergoeshere { + display: none; + } +} diff --git a/website/themes/uswds-nist/config.yaml b/website/themes/uswds-nist/config.yaml new file mode 100644 index 000000000..c8304dbf7 --- /dev/null +++ b/website/themes/uswds-nist/config.yaml @@ -0,0 +1,25 @@ +name: "The United States Web Design System (USWDS) 2.0 Hugo Theme NIST Customization" +license: "CCO" +licenselink: "https://github.com/usnistgov/hugo-uswds/blob/master/LICENSE.md" +description: "A hugo theme based on the United States Web Design System (USWDS) 2.0" +homepage: "https://github.com/usnistgov/hugo-uswds" +tags: +features: +min_version: "0.111.0" +author: + name: "David Waltermire" + homepage: "https://www.nist.gov/people/david-waltermire" +module: + hugoVersion: + min: 0.111.0 + extended: true + mounts: + - source: layouts + target: layouts + - source: archetypes + target: archetypes + - source: static + target: static + - source: assets + target: assets + diff --git a/website/themes/uswds-nist/layouts/partials/foot.html b/website/themes/uswds-nist/layouts/partials/foot.html new file mode 100644 index 000000000..3c64fe74c --- /dev/null +++ b/website/themes/uswds-nist/layouts/partials/foot.html @@ -0,0 +1,30 @@ +
      + + diff --git a/website/themes/uswds-nist/layouts/partials/head.html b/website/themes/uswds-nist/layouts/partials/head.html new file mode 100644 index 000000000..c5b12dc26 --- /dev/null +++ b/website/themes/uswds-nist/layouts/partials/head.html @@ -0,0 +1,2 @@ + + diff --git a/website/themes/uswds-nist/layouts/partials/top-banner.html b/website/themes/uswds-nist/layouts/partials/top-banner.html new file mode 100644 index 000000000..d655ac407 --- /dev/null +++ b/website/themes/uswds-nist/layouts/partials/top-banner.html @@ -0,0 +1 @@ +