diff --git a/build/ci-cd/README.md b/build/ci-cd/README.md index 965b2d8f1e..2198764077 100644 --- a/build/ci-cd/README.md +++ b/build/ci-cd/README.md @@ -1,30 +1,33 @@ # Continuous Integration and Continuous Deployment (CI/CD) This GitHub repository uses a CI/CD process that provides automation for: + - Validation of contributed content and models. - Generation of documentation, content converters, and content in alternate formats. - Methods to update the [project website](https://pages.nist.gov/OSCAL). Using a CI/CD process ensures that all artifacts in [pull requests](https://github.com/usnistgov/OSCAL/blob/master/CONTRIBUTING.md) and in the [master branch](https://github.com/usnistgov/OSCAL) are valid and usable. -# Provided Scripts +## Provided Scripts The primary CircleCI supported CI/CD workflow, ```build```, is uses a series of bash scripts. The following scripts are used in this workflow for all PRs that are submitted: 1. [run-all.sh](run-all.sh): Runs all of the scripts in workflow order. -1. [validate-metaschema.sh](validate-metaschema.sh): Ensures that all [metaschema](https://github.com/usnistgov/OSCAL/tree/master/src/metaschema) are valid according to the [metaschema XML schema](https://github.com/usnistgov/metaschema/blob/master/toolchains/oscal-m2/lib/metaschema.xsd). +1. [validate-metaschema.sh](validate-metaschema.sh): Ensures that all [metaschema](https://github.com/usnistgov/OSCAL/tree/master/src/metaschema) are valid according to the [metaschema XML schema](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema.xsd). 1. [generate-schema.sh](generate-schema.sh): Generates [XML schema](https://github.com/usnistgov/OSCAL/tree/master/xml/schema) and [JSON schema](https://github.com/usnistgov/OSCAL/tree/master/json/schema) files for each OSCAL model based on their [respective metaschemas](https://github.com/usnistgov/OSCAL/tree/master/src/metaschema). 1. [validate-content.sh](validate-content.sh): Validates OSCAL content in the repository's [src](https://github.com/usnistgov/OSCAL/tree/master/src) against the content's respective OSCAL model and format. 1. [generate-content-converters.sh](generate-content-converters.sh): Generates [JSON to XML](https://github.com/usnistgov/OSCAL/tree/master/xml/convert) and [XML to JSON](https://github.com/usnistgov/OSCAL/tree/master/json/convert) content conversion scripts for each OSCAL model based on their [respective metaschemas](https://github.com/usnistgov/OSCAL/tree/master/src/metaschema). 1. [copy-and-convert-content.sh](copy-and-convert-content.sh): Copies selective content from the [src/content](https://github.com/usnistgov/OSCAL/tree/master/src/content) directory, and generates instance of this content in alternate OSCAL formats using the appropriate content converters. Note __This script requires that the process have write access to the Git repository branch that the CI/CD is operating on to work completely.__ 1. [validate-content-conversion-round-trips.sh](validate-content-conversion-round-trips.sh): Performs round trip validations of the content from XML->JSON->XML to confirm that the conversions are lossless and that resulting files comply with their schemas. -Additional scripts are provided that generate content for the OSCAL project website, supported by the CircleCI ```build``` workflow on the ```master``` branch. + Additional scripts are provided that generate content for the OSCAL project website, supported by the CircleCI ```build``` workflow on the ```master``` branch. + 1. [generate-model-documentation.sh](generate-model-documentation.sh): This is used as part of the site generation pipeline to build HTML documentation for the OSCAL models. -# Running the Scripts Locally +## Running the Scripts Locally The bash scripts used in the CI/CD workflow can be run locally in the correct environment. In addition to a bash shell, to run these scripts the following must be installed: + - [xmlint](http://xmlsoft.org/xmllint.html) - [Java](https://www.java.com/en/) 8.0 or greater - [Apache Maven](https://maven.apache.org/) 3.6.1 or greater @@ -36,92 +39,90 @@ Additionally, the following packages need to be installed. NodeJS Packages: -``` +```bash npm install -g ajv-cli ``` Python Packages: -``` +```bash pip install lxml ``` The Saxon jar file needs to be retrieved. This can be two ways: -1) You can set the environment variable ```SAXON_VERSION``` to the Saxon version to use. This must correspond to a valid Saxon-HE version in [Maven Central](https://search.maven.org/artifact/net.sf.saxon/Saxon-HE). Maven will be used to automatically download the Saxon-HE jar dependency. +1. You can set the environment variable ```SAXON_VERSION``` to the Saxon version to use. This must correspond to a valid Saxon-HE version in [Maven Central](https://search.maven.org/artifact/net.sf.saxon/Saxon-HE). Maven will be used to automatically download the Saxon-HE jar dependency. -For example: + For example: -``` -export SAXON_VERSION=9.9.1-3 -``` + ```bash + export SAXON_VERSION=9.9.1-3 + ``` -2) You can manually download any variant of Saxon (e.g., HE, ) from [Saxonica](https://www.saxonica.com/download/java.xml) and set the ```SAXON_HOME``` environment variable to the location of the Saxon JAR. +2. You can manually download any variant of Saxon (e.g., HE, ) from [Saxonica](https://www.saxonica.com/download/java.xml) and set the ```SAXON_HOME``` environment variable to the location of the Saxon JAR. -``` +```bash export SAXON_HOME=~/saxon-jar-directory ``` Finally, the Schematron Skeleton needs to be retrieved. The following commands can be used to download it. -``` +```bash export SCHEMATRON_HOME=~/schematron-skeleton git clone --depth 1 --no-checkout https://github.com/Schematron/schematron.git "$SCHEMATRON_HOME" cd "$SCHEMATRON_HOME" git checkout master -- trunk/schematron/code ``` -## Further installation notes +### Further installation notes Setting up to run in WSL (Windows subsystem for Linux) avoids many Windows-related configuration issues, but requires the entire environment be available from within the subsystem. The easiest way to accomplish this is to install the components into the subsystem directly. To check whether xmllint is installed: -``` +```bash xmllint -version ``` To install it -``` +```bash sudo apt install libxml2-utils ``` To install Java: -``` +```bash sudo apt install openjdk-11-jre-headless ``` To install NodeJS: -``` +```bash sudo apt install nodejs ``` And npm (Node package manager, separate from NodeJS): -``` +```bash sudo apt install npm ``` - To install AJV (nodeJS JSON validator) -``` +```bash npm install -g ajv-cli ``` - or if you want to install globally (for all users): -``` +```bash sudo npm install -g ajv-cli ``` Ubuntu comes with Python. To check the version: -``` +```bash python3 -V ``` @@ -129,30 +130,28 @@ Scripts were tested with version 3.7.3 but 3.6.8 (the default in Ubuntu under WS Along with Python you also need a library, for which you need pip (a Python installer): -``` +```bash sudo apt install python-pip pip install lxml ``` - To install Maven: -``` +```bash sudo apt install maven ``` Then run Maven to acquire Saxon: - -``` +```bash export SAXON_VERSION=9.9.1-3 mvn org.apache.maven.plugins:maven-dependency-plugin:2.10:get -DartifactId=Saxon-HE -DgroupId=net.sf.saxon -Dversion=$SAXON_VERSION ``` You will also need a copy of the ISO Schematron skeleton. -``` +```bash mkdir $HOME/oscal-oss export SCHEMATRON_HOME=$HOME/oscal-oss/git-schematron git clone --depth 1 --no-checkout https://github.com/Schematron/schematron.git "$SCHEMATRON_HOME" @@ -164,12 +163,12 @@ Finally, export instructions in the preceding must also be copied into .bashrc s prettyson -``` +```bash sudo npm install -g prettyjson ``` jq -``` +```bash sudo apt-get install jq ``` diff --git a/build/metaschema b/build/metaschema index 1b090948e9..25a56e7810 160000 --- a/build/metaschema +++ b/build/metaschema @@ -1 +1 @@ -Subproject commit 1b090948e9319379d4c26c9f33e2fcc46b1d2a6b +Subproject commit 25a56e7810d3f4602ddd09c7feac528d4c6326de diff --git a/src/metaschema/oscal_assessment-common_metaschema.xml b/src/metaschema/oscal_assessment-common_metaschema.xml index a2be9f79e0..bff93b60b4 100644 --- a/src/metaschema/oscal_assessment-common_metaschema.xml +++ b/src/metaschema/oscal_assessment-common_metaschema.xml @@ -66,10 +66,10 @@ - + - + @@ -157,7 +157,7 @@ - +

Since multiple party-uuid entries can be provided, each role-id must be referenced only once.

@@ -190,7 +190,7 @@ The process of reviewing, inspecting, observing, studying, or analyzing one or more assessment objects (i.e., specifications, mechanisms, or activities). The process of exercising one or more assessment objects (i.e., activities or mechanisms) under specified conditions to compare actual with expected behavior. - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -331,7 +331,7 @@ --> - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -687,7 +687,7 @@ - +

Since responsible-party associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -700,7 +700,7 @@
- +

Since multiple assessment component entries can be provided, each component must have a unique uuid.

@@ -887,18 +887,18 @@ - - - - +
+--> Origin @@ -994,7 +994,7 @@ - +

Since responsible-party associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -1194,7 +1194,7 @@ The type of remediation tracking entry. Can be multi-valued. - + Contacted vendor to determine the status of a pending fix to a known vulnerability. Information related to the current state of response to this risk. A significant step in the response plan has been achieved. @@ -1587,12 +1587,6 @@ - - - The UUID of the person or organization who made the recommendation - The UUID of the tool that made the recommendation - -
diff --git a/src/metaschema/oscal_assessment-plan_metaschema.xml b/src/metaschema/oscal_assessment-plan_metaschema.xml index 13a5ff80b1..9bef67975c 100644 --- a/src/metaschema/oscal_assessment-plan_metaschema.xml +++ b/src/metaschema/oscal_assessment-plan_metaschema.xml @@ -67,13 +67,13 @@ - +

Since multiple component entries can be provided, each component must have a unique uuid.

- +

A given uuid must be assigned only once to a user.

diff --git a/src/metaschema/oscal_assessment-results_metaschema.xml b/src/metaschema/oscal_assessment-results_metaschema.xml index 10fa3cab36..ebb24f1b5c 100644 --- a/src/metaschema/oscal_assessment-results_metaschema.xml +++ b/src/metaschema/oscal_assessment-results_metaschema.xml @@ -141,13 +141,13 @@
- +

Since multiple component entries can be provided, each component must have a unique uuid.

- +

A given uuid must be assigned only once to a user.

@@ -179,7 +179,7 @@ - +

Since responsible-party associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

diff --git a/src/metaschema/oscal_catalog_metaschema.xml b/src/metaschema/oscal_catalog_metaschema.xml index c40f334116..92385a917a 100644 --- a/src/metaschema/oscal_catalog_metaschema.xml +++ b/src/metaschema/oscal_catalog_metaschema.xml @@ -45,9 +45,6 @@
- - -

Catalogs may use one or more group objects to subdivide the control contents of a catalog.

An OSCAL catalog model provides a structured representation of control information.

diff --git a/src/metaschema/oscal_complete_metaschema.xml b/src/metaschema/oscal_complete_metaschema.xml index 82989c7ff9..f8e91c0266 100644 --- a/src/metaschema/oscal_complete_metaschema.xml +++ b/src/metaschema/oscal_complete_metaschema.xml @@ -3,7 +3,7 @@ + ]> OSCAL Unified Model of Models diff --git a/src/metaschema/oscal_component_metaschema.xml b/src/metaschema/oscal_component_metaschema.xml index ed1880ef2f..7a9fe80aec 100644 --- a/src/metaschema/oscal_component_metaschema.xml +++ b/src/metaschema/oscal_component_metaschema.xml @@ -1,15 +1,15 @@ - - - - - - - - + + + + + + + + + ]> @@ -56,7 +56,7 @@

Since multiple component entries can be provided, each component must have a unique uuid.

- +

A given component must not be referenced more than once within the same capability.

@@ -147,7 +147,7 @@ This component uses the network provided by the identified network component. - + @@ -164,7 +164,7 @@ - + The component allows an authenticated scan. The component does not allow an authenticated scan. @@ -211,7 +211,7 @@ &allowed-values-component_component_service; - + @@ -219,7 +219,7 @@ - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -275,7 +275,7 @@ - +

A given component must not be referenced more than once within the same capability.

@@ -330,7 +330,7 @@ - +

Since multiple set-parameter entries can be provided, each parameter must be set only once.

@@ -372,19 +372,19 @@ - +

Since multiple set-parameter entries can be provided, each parameter must be set only once.

- +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

- +

Since statement entries can be referenced using the statement's statement-id, each statement must be referenced only once.

@@ -421,7 +421,7 @@ - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

diff --git a/src/metaschema/oscal_control-common_metaschema.xml b/src/metaschema/oscal_control-common_metaschema.xml index 373fb83473..29e616be61 100644 --- a/src/metaschema/oscal_control-common_metaschema.xml +++ b/src/metaschema/oscal_control-common_metaschema.xml @@ -3,7 +3,7 @@ + ]> diff --git a/src/metaschema/oscal_implementation-common_metaschema.xml b/src/metaschema/oscal_implementation-common_metaschema.xml index a6dd0b6bf7..6829307fef 100644 --- a/src/metaschema/oscal_implementation-common_metaschema.xml +++ b/src/metaschema/oscal_implementation-common_metaschema.xml @@ -1,15 +1,15 @@ - - - - - - - - + + + + + + + + + ]> @@ -181,7 +181,7 @@ &allowed-values-component_component_service;
- + @@ -194,7 +194,7 @@ An Internet Protocol Version 6 interconnection address An Internet Protocol Version 6 interconnection address
- + The identified IP address is for this system. The identified IP address is for the remote system to which this system is connected. @@ -211,11 +211,11 @@ - + Data from the remote system flows into this system. Data from this system flows to the remote system. - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -238,7 +238,7 @@ The system as a whole. An external system, which may be a leveraged system or the other side of an interconnection. - &allowed-values-component-type; + &allowed-values-component-type; A physical or virtual network.
@@ -510,7 +510,7 @@ - +

Since responsible-party associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -581,9 +581,9 @@ - + - +

Since responsible-party associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

diff --git a/src/metaschema/oscal_metadata_metaschema.xml b/src/metaschema/oscal_metadata_metaschema.xml index f306a51b58..7ae1c7acbd 100644 --- a/src/metaschema/oscal_metadata_metaschema.xml +++ b/src/metaschema/oscal_metadata_metaschema.xml @@ -58,21 +58,21 @@ - + - + - + - - + + - + @@ -94,7 +94,7 @@ - +

Since responsible-party associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -214,9 +214,9 @@ - + - + @@ -228,7 +228,7 @@ - + @@ -312,7 +312,7 @@ - + @@ -338,7 +338,7 @@ - + @@ -387,7 +387,7 @@ - + @@ -528,13 +528,13 @@ Indicates the resource is a formal agreement between two or more parties. - +

Ensures that each rlink item references a unique resource.

- +

Ensures that all base64 resources have a unique filename. @@ -733,7 +733,7 @@ - + diff --git a/src/metaschema/oscal_poam_metaschema.xml b/src/metaschema/oscal_poam_metaschema.xml index 8b899625de..bce14bc6be 100644 --- a/src/metaschema/oscal_poam_metaschema.xml +++ b/src/metaschema/oscal_poam_metaschema.xml @@ -74,7 +74,7 @@ - +

Since multiple component entries can be provided, each component must have a unique uuid.

diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index 2066fb9ff0..a573ee5ef5 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -1,7 +1,7 @@ + ]> @@ -246,19 +246,20 @@ - - - - -

Since multiple set-parameter entries can be provided, each parameter must be set only once.

-
-
-
+ + + + +

Since multiple set-parameter entries can be provided, each parameter must be set only once.

+
+
+
+ Select controls diff --git a/src/metaschema/oscal_ssp_metaschema.xml b/src/metaschema/oscal_ssp_metaschema.xml index 6d8266b478..295356ec2e 100644 --- a/src/metaschema/oscal_ssp_metaschema.xml +++ b/src/metaschema/oscal_ssp_metaschema.xml @@ -6,9 +6,9 @@ - - + + + ]> @@ -126,7 +126,7 @@ A value of 1, 2, or 3 as defined by SP 800-63-3. - + As defined by SP 800-63-3. As defined by SP 800-63-3. @@ -134,11 +134,11 @@ As defined by SP 800-63-3. - + The associated value is one of: public-cloud, private-cloud, community-cloud, government-only-cloud, hybrid-cloud, or other. The associated value is one of: saas, paas, iaas, or other. - + The public cloud deployment model as defined by The NIST Definition of Cloud Computing. The private cloud deployment model as defined by The NIST Definition of Cloud Computing. @@ -152,7 +152,7 @@

The hybrid cloud deployment model, as defined by The NIST Definition of Cloud Computing, can be supported by selecting two or more of the existing deployment models.

- + Software as a service (SaaS) cloud service model as defined by The NIST Definition of Cloud Computing. Platform as a service (PaaS) cloud service model as defined by The NIST Definition of Cloud Computing. @@ -161,7 +161,7 @@ Any other type of cloud service model that is exclusive to the other choices. - +

Since responsible-party associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -284,7 +284,7 @@ Is this a privacy sensitive system? yes or no - + The system is privacy sensitive. The system isnot privacy sensitive. @@ -292,11 +292,11 @@ A link to the privacy impact assessment. - + - + A 'low' sensitivity level as defined in FIPS-199. A 'moderate' sensitivity level as defined in FIPS-199. @@ -396,7 +396,7 @@ - +

A given uuid must be assigned only once to a diagram.

@@ -439,8 +439,8 @@ A reference to the diagram image. - - + + @@ -479,7 +479,7 @@ - +

A given uuid must be assigned only once to a diagram.

@@ -509,7 +509,7 @@ - +

A given uuid must be assigned only once to a diagram.

@@ -564,7 +564,7 @@ A reference to the system security plan for the leveraged authorization.
- + @@ -597,7 +597,7 @@
- + @@ -642,7 +642,7 @@ - +

A given uuid must be assigned only once to a user.

@@ -667,7 +667,7 @@ - +

Since multiple set-parameter entries can be provided, each parameter must be set only once.

@@ -727,35 +727,35 @@ &allowed-values-responsible-roles-operations; - + - +

Since all implementation statements are defined at the by-component level (e.g., type=this-system), there must be at least one by-component.

- +

Since multiple set-parameter entries can be provided, each parameter must be set only once.

- +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

- +

Since statement entries can be referenced using the statement's statement-id, each statement must be referenced only once.

- +

Since by-component can reference component entries using the component's uuid, each component must be referenced only once. This ensures that all implementation statements are contained in the same by-component entry.

@@ -794,13 +794,13 @@ &allowed-values-responsible-roles-operations; - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

- +

Since by-component can reference component entries using the component's uuid, each component must be referenced only once. This ensures that all implementation statements are contained in the same by-component entry.

@@ -882,7 +882,7 @@ - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -920,7 +920,7 @@ - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -932,7 +932,7 @@ - + @@ -967,7 +967,7 @@ - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -1003,7 +1003,7 @@ - +

Since responsible-role associates multiple party-uuid entries with a single role-id, each role-id must be referenced only once.

@@ -1022,7 +1022,7 @@ &allowed-values-responsible-roles-operations; &allowed-values-responsible-roles-component-production; - +

Since multiple set-parameter entries can be provided, each parameter must be set only once.

diff --git a/src/metaschema/readme.md b/src/metaschema/readme.md index d0437c1db0..6f6de48646 100644 --- a/src/metaschema/readme.md +++ b/src/metaschema/readme.md @@ -10,9 +10,9 @@ OSCAL Metaschemas are used to generate other OSCAL artifacts based on the metasc Use of Metaschemas in OSCAL allow us to maintain seamless and consistent support for multiple OSCAL model formats, including XML and JSON. Content can also be kept up-to-date in multiple formats using generated content converters, and can be validated using generated schema. Adding support for new formats (e.g., YAML) can accomplished by extending the Metaschema tooling to produce schema and converters for other formats. -The Metaschema syntax (an XML application) is also described and constrained with its [own schema](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema.xsd), and with a [Schematron constraints set](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema-check.sch). The latter is able to enforce some of the rules described below. +The Metaschema syntax (an XML application) is also described and constrained with its [own schema](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema.xsd), and with a [Schematron constraints set](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema-composition-check.sch). The latter is able to enforce some of the rules described below. -#### Enumerated values +## Enumerated values Additionally, flags may be constrained to a set of known values listed in advance. @@ -34,6 +34,7 @@ Within it `valid-values`, a `value` element's `@name` attribute assigns the perm ... ``` + ## 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. @@ -44,13 +45,12 @@ Among these elements, no single `@named` attribute value (which refers a model c 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. - +- `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 @@ -60,20 +60,18 @@ One problem with zero-or-more cardinality as supported by `fields` and `assembli 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 assembly, 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. +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 assembly, such flag is assumed to be unique and valid 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. - - -``` +```xml ``` -``` +```xml Water (H<sub>2</sub>0) ``` -``` +```xml "title" : "Water (H~~2~~0)" ```