From 6848c796bd440c90a734600a665c53c33e103d22 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Mon, 18 Sep 2023 18:55:24 -0400 Subject: [PATCH 01/13] [WIP] Configured lychee and GHA * Some requests are malformed due to the hugo base path --- .github/workflows/pages.yaml | 72 ++++++++++++++++++++++++++++++++---- .gitignore | 2 + Makefile | 19 ++++++++++ support/lychee.toml | 8 ++++ support/lychee_ignore.txt | 15 ++++++++ 5 files changed, 109 insertions(+), 7 deletions(-) create mode 100644 .gitignore create mode 100644 support/lychee.toml create mode 100644 support/lychee_ignore.txt diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index ce7ee5083..caf9a3279 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -4,28 +4,62 @@ on: branches: - main pull_request: {} + workflow_dispatch: + inputs: + swapSizeGb: + description: The amount of swap to allocate + default: 10 + required: false + type: number + ignore_linkcheck: + description: Ignore link checker results when deploying + required: false + default: false + type: boolean +env: + LYCHEE_VERSION: "0.13.0" + HUGO_VERSION: "0.118.2" + JAVA_VERSION: "17" + JAVA_DISTRIBUTION: "temurin" jobs: deploy: runs-on: ubuntu-22.04 steps: + # + # Environment setup + # - uses: actions/checkout@v3 with: submodules: true fetch-depth: 0 - uses: actions/setup-java@v3 with: - distribution: "temurin" - java-version: "17" + distribution: "${{ env.JAVA_DISTRIBUTION }}" + java-version: "${{ env.JAVA_VERSION }}" - name: Setup Hugo uses: peaceiris/actions-hugo@v2 with: hugo-version: "0.118.2" extended: true + # lifted from https://github.com/lycheeverse/lychee-action/blob/master/action.yml + - name: Setup Lychee + run: | + # Cleanup artifacts from previous run in case it crashed + rm -rf "lychee-v${{ env.LYCHEE_VERSION }}-x86_64-unknown-linux-gnu.tar.gz" lychee + curl -sLO "https://github.com/lycheeverse/lychee/releases/download/v${{ env.LYCHEE_VERSION }}/lychee-v${{ env.LYCHEE_VERSION }}-x86_64-unknown-linux-gnu.tar.gz" + tar -xvzf "lychee-v${{ env.LYCHEE_VERSION }}-x86_64-unknown-linux-gnu.tar.gz" + rm "lychee-v${{ env.LYCHEE_VERSION }}-x86_64-unknown-linux-gnu.tar.gz" + install -t "$HOME/.local/bin" -D lychee + rm lychee + echo "$HOME/.local/bin" >> "$GITHUB_PATH" - name: Setup swap space # The Hugo build can require a significant amount of memory uses: pierotofy/set-swap-space@49819abfb41bd9b44fb781159c033dba90353a7c with: - swap-size-gb: 10 + swap-size-gb: ${{ github.event.inputs.swapSizeGb }} + # + # Set up cache + # - name: Get the list of tagged revisions (for cache) id: get-revisions run: | @@ -38,21 +72,45 @@ jobs: path: | site/content/models/v*/ site/data/models/v*/ - key: ${{ hashFiles('site/archetypes/**') }}-${{ hashFiles('support/*.sh') }}-${{ steps.get-revisions.outputs.revisions_hash }} + key: cache-models-${{ hashFiles('site/archetypes/**') }}-${{ hashFiles('support/*.sh') }}-${{ steps.get-revisions.outputs.revisions_hash }} # A new tagged revision will invalidate the primary cache key # See https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache restore-keys: | - ${{ hashFiles('site/archetypes/**') }}-${{ hashFiles('support/*.sh') }} + cache-models-${{ hashFiles('site/archetypes/**') }}-${{ hashFiles('support/*.sh') }} + # Cache lychee results (e.g. to avoid hitting rate limits) + - name: Restore lychee cache + uses: actions/cache@v3 + with: + path: .lycheecache + key: cache-lychee-${{ github.sha }} + restore-keys: cache-lychee- + # + # Build + # - name: Build # https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources # GHA runners have 2 CPUs run: make site -j2 + # + # Checks (and check plumbing) + # + - name: Link Check + id: linkcheck + run: make linkcheck LYCHEE_EXTRA_FLAGS='--github-token ${{ secrets.GITHUB_TOKEN }}' + # TODO + # - name: Comment Broken Links + # uses: marocchino/sticky-pull-request-comment@v2 + # with: + # path: lychee_report.md + # + # Deployment + # - name: Deploy uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 - if: github.ref == 'refs/heads/main' + # Deploy if on main branch and EITHER the linkcheck succeeds or ignore_linkcheck has been flipped + if: github.ref == 'refs/heads/main' && (steps.linkcheck.outcome == 'success' || github.event.inputs.ignore_linkcheck) with: github_token: ${{ secrets.GITHUB_TOKEN }} - # personal_token: ${{ secrets.COMMIT_TOKEN }} enable_jekyll: false publish_dir: ./site/public publish_branch: nist-pages diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..e2584e978 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +lychee_report.md +.lycheecache diff --git a/Makefile b/Makefile index 22286a72f..5cc1a474f 100644 --- a/Makefile +++ b/Makefile @@ -69,3 +69,22 @@ $(RELEASE_ASSET_REDIRECTS_DIR): .PHONY: clean-release-assets clean-release-assets: ## Clean release redirects rm -fr site/content/release-assets/latest/ + +# +# Checks +# + +LYCHEE_IGNORE_FILE:=./support/lychee_ignore.txt +LYCHEE_CONFIG_FILE:=./support/lychee.toml +# Flags that currently cannot be configured via the configuration file +LYCHEE_FLAGS:=--verbose --format markdown +# Extra flags for the user to override (used to set github token in GHA workflow) +LYCHEE_EXTRA_FLAGS:= + +.PHONY: linkcheck +linkcheck: site + lychee \ + --exclude-file '$(LYCHEE_IGNORE_FILE)' \ + --config '$(LYCHEE_CONFIG_FILE)' \ + $(LYCHEE_FLAGS) $(LYCHEE_EXTRA_FLAGS) \ + '$(SITE_OUTPUT)/**/*.html' diff --git a/support/lychee.toml b/support/lychee.toml new file mode 100644 index 000000000..9f4b226de --- /dev/null +++ b/support/lychee.toml @@ -0,0 +1,8 @@ +no_progress = true +exclude_mail = true +accept = [200, 206, 429] + +cache = true + +output = "lychee_report.md" +# format = "markdown" # currently does not exist, must specify --format markdown diff --git a/support/lychee_ignore.txt b/support/lychee_ignore.txt new file mode 100644 index 000000000..260b61e7e --- /dev/null +++ b/support/lychee_ignore.txt @@ -0,0 +1,15 @@ +https://defense.gov/ +https://federal-agency.gov/.* +http://federal-agency.gov/ns/oscal +http://fedramp.gov/ns/oscal +https://fedramp.gov/ns/oscal +http://www.first.org/cvss/v2.0 +http://www.first.org/cvss/v3.0 +http://www.first.org/cvss/v3.1 +https://tools.ietf.org/html.* +http://csrc.nist.gov/ns/.* +http://csrc.nist.gov/oscal +https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/xxxx +https://cdn.telos.com/wp-content/uploads/2021/06/22150746/Xacta-360-EULA-US.pdf +https://search.usa.gov/search +https://example.com/.* From cf82d29cb6690b6dae47ee6d04967fcca582f7e1 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Tue, 19 Sep 2023 09:36:17 -0400 Subject: [PATCH 02/13] [WIP] Correct swap size parameterization --- .github/workflows/pages.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index caf9a3279..6c378e698 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -6,7 +6,7 @@ on: pull_request: {} workflow_dispatch: inputs: - swapSizeGb: + swap_size_gb: description: The amount of swap to allocate default: 10 required: false @@ -56,7 +56,7 @@ jobs: # The Hugo build can require a significant amount of memory uses: pierotofy/set-swap-space@49819abfb41bd9b44fb781159c033dba90353a7c with: - swap-size-gb: ${{ github.event.inputs.swapSizeGb }} + swap-size-gb: "10" # # Set up cache # From 456ddff7891fce46569e339adf2b7e649f00e935 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Tue, 19 Sep 2023 10:46:54 -0400 Subject: [PATCH 03/13] [WIP] Do not rebuild the site on linkcheck --- .github/workflows/pages.yaml | 5 ----- Makefile | 28 +++++++++++++++++++--------- support/lychee.toml | 1 - 3 files changed, 19 insertions(+), 15 deletions(-) diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index 6c378e698..a91135153 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -6,11 +6,6 @@ on: pull_request: {} workflow_dispatch: inputs: - swap_size_gb: - description: The amount of swap to allocate - default: 10 - required: false - type: number ignore_linkcheck: description: Ignore link checker results when deploying required: false diff --git a/Makefile b/Makefile index 5cc1a474f..86aa892ac 100644 --- a/Makefile +++ b/Makefile @@ -6,37 +6,40 @@ SHELL:=/usr/bin/env bash help: ## Show this help message @grep -E '^[a-zA-Z_-]+:.*?##.*$$' $(MAKEFILE_LIST) | awk 'BEGIN { \ FS = ":.*?## "; \ - printf "\033[1m%-30s\033[0m %s\n", "TARGET", "DESCRIPTION" \ + printf "\033[1m%-30s %s\033[0m\n", "TARGET", "DESCRIPTION" \ } \ { printf "\033[32m%-30s\033[0m %s\n", $$1, $$2 }' .PHONY: clean -clean: clean-modeldoc clean-site clean-release-assets ## Clean all +clean: clean-modeldoc clean-site clean-release-assets clean-linkcheck ## Clean all # # Website generation / hugo # +# Override REVISIONS to build a subset of the site or a special branch +# (e.g. `make site REVISIONS='v1.1.0 my-special-branch'`) REVISIONS:=develop $(shell ./support/list_revisions.sh) + MODELDOC_CONTENT_DIR:=site/content/models MODELDOC_REVISION_CONTENT_DIR:=$(patsubst %,$(MODELDOC_CONTENT_DIR)/%/,$(REVISIONS)) MODELDOC_DATA_DIR:=site/data/models MODELDOC_REVISION_DATA_DIR:=$(patsubst %,$(MODELDOC_DATA_DIR)/%/,$(REVISIONS)) -SITE_OUTPUT:=site/public +SITE_OUTPUT_DIR:=site/public .PHONY: serve serve: modeldoc release-assets ## Spin up a static web server for local dev cd site; hugo serve .PHONY: site -site: $(SITE_OUTPUT) ## Build the site +site: $(SITE_OUTPUT_DIR) ## Build the site -$(SITE_OUTPUT): modeldoc release-assets +$(SITE_OUTPUT_DIR): $(MODELDOC_REVISION_CONTENT_DIR) $(RELEASE_ASSET_REDIRECTS_DIR) cd site; hugo --minify .PHONY: clean-site clean-site: ## Clean the site - rm -fr $(SITE_OUTPUT) + rm -fr $(SITE_OUTPUT_DIR) # # Model documentation @@ -68,12 +71,13 @@ $(RELEASE_ASSET_REDIRECTS_DIR): .PHONY: clean-release-assets clean-release-assets: ## Clean release redirects - rm -fr site/content/release-assets/latest/ + rm -fr $(RELEASE_ASSET_REDIRECTS_DIR) # # Checks # +LYCHEE_OUTPUT_FILE:=lychee_report.md LYCHEE_IGNORE_FILE:=./support/lychee_ignore.txt LYCHEE_CONFIG_FILE:=./support/lychee.toml # Flags that currently cannot be configured via the configuration file @@ -82,9 +86,15 @@ LYCHEE_FLAGS:=--verbose --format markdown LYCHEE_EXTRA_FLAGS:= .PHONY: linkcheck -linkcheck: site +linkcheck: $(LYCHEE_OUTPUT_FILE) ## Generate a report of all site links + +$(LYCHEE_OUTPUT_FILE): $(SITE_OUTPUT_DIR) lychee \ --exclude-file '$(LYCHEE_IGNORE_FILE)' \ --config '$(LYCHEE_CONFIG_FILE)' \ + --output $(LYCHEE_OUTPUT_FILE) \ $(LYCHEE_FLAGS) $(LYCHEE_EXTRA_FLAGS) \ - '$(SITE_OUTPUT)/**/*.html' + '$(SITE_OUTPUT_DIR)/**/*.html' + +clean-linkcheck: ## Clean the linkcheck report + rm -f $(LYCHEE_OUTPUT_FILE) diff --git a/support/lychee.toml b/support/lychee.toml index 9f4b226de..ffee45b39 100644 --- a/support/lychee.toml +++ b/support/lychee.toml @@ -4,5 +4,4 @@ accept = [200, 206, 429] cache = true -output = "lychee_report.md" # format = "markdown" # currently does not exist, must specify --format markdown From 1320d7d531721fad81cce17133c6e9edb89bf742 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Fri, 22 Sep 2023 14:48:08 -0400 Subject: [PATCH 04/13] Revert `HUGO_VERSION` env --- .github/workflows/pages.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index a91135153..59aadbbfc 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -34,7 +34,7 @@ jobs: - name: Setup Hugo uses: peaceiris/actions-hugo@v2 with: - hugo-version: "0.118.2" + hugo-version: "${{ env.HUGO_VERSION }}" extended: true # lifted from https://github.com/lycheeverse/lychee-action/blob/master/action.yml - name: Setup Lychee From 50e84f537dd89f28088c0640a893401c285780c0 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Mon, 25 Sep 2023 12:07:05 -0400 Subject: [PATCH 05/13] Correct links to metaschema and schema files * Ignore DOI links --- site/archetypes/complete-reference/json-definitions.md | 2 +- site/archetypes/complete-reference/json-index.md | 2 +- site/archetypes/complete-reference/json-outline.md | 2 +- site/archetypes/complete-reference/xml-definitions.md | 2 +- site/archetypes/complete-reference/xml-index.md | 2 +- site/archetypes/complete-reference/xml-outline.md | 2 +- site/archetypes/model-reference/_index.md | 2 +- site/archetypes/model-reference/json-definitions.md | 2 +- site/archetypes/model-reference/json-index.md | 2 +- site/archetypes/model-reference/json-outline.md | 2 +- site/archetypes/model-reference/xml-definitions.md | 2 +- site/archetypes/model-reference/xml-index.md | 2 +- site/archetypes/model-reference/xml-outline.md | 2 +- support/generate_modeldoc.sh | 3 +++ support/lychee.toml | 2 -- support/lychee_ignore.txt | 2 ++ 16 files changed, 18 insertions(+), 15 deletions(-) diff --git a/site/archetypes/complete-reference/json-definitions.md b/site/archetypes/complete-reference/json-definitions.md index 294816ad1..9c4f42d67 100644 --- a/site/archetypes/complete-reference/json-definitions.md +++ b/site/archetypes/complete-reference/json-definitions.md @@ -14,7 +14,7 @@ aliases: {{ end }} --- -The following is a reference for the JSON object definitions derived from this model's [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_metaschema.xml), which imports the metaschemas for all of the OSCAL models. +The following is a reference for the JSON object definitions derived from this model's [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_metaschema.xml), which imports the metaschemas for all of the OSCAL models. {{< rawhtml >}} {{ os.ReadFile (printf "%s/%s" (getenv "HUGO_MODEL_DATA_DIR") "json-definitions.html") }} diff --git a/site/archetypes/complete-reference/json-index.md b/site/archetypes/complete-reference/json-index.md index f109f7011..24180563f 100644 --- a/site/archetypes/complete-reference/json-index.md +++ b/site/archetypes/complete-reference/json-index.md @@ -15,7 +15,7 @@ aliases: --- The following is an index of each JSON property used in the JSON format, which represents the combination of all OSCAL models. -The combined schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.json){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. +The combined schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_schema.json){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. Each entry in the index lists all uses of the given property in the format, which is linked to the corresponding entry in the [JSON Format Reference](../json-reference/). Each entry also lists the formal name for the definition which is linked to the corresponding JSON definition in the [JSON Format Metaschema Reference](../json-definitions/). diff --git a/site/archetypes/complete-reference/json-outline.md b/site/archetypes/complete-reference/json-outline.md index 3ae549300..879155c22 100644 --- a/site/archetypes/complete-reference/json-outline.md +++ b/site/archetypes/complete-reference/json-outline.md @@ -14,7 +14,7 @@ aliases: --- The following outline is a representation of the JSON format for the combination of all OSCAL models. -The combined schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.json){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. +The combined schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_schema.json){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. For each property, the name links to the corresponding entry in the [JSON Format Reference](../json-reference/). The cardinality and data type are also provided for each property where appropriate. diff --git a/site/archetypes/complete-reference/xml-definitions.md b/site/archetypes/complete-reference/xml-definitions.md index c333588b3..e09fc8319 100644 --- a/site/archetypes/complete-reference/xml-definitions.md +++ b/site/archetypes/complete-reference/xml-definitions.md @@ -14,7 +14,7 @@ aliases: {{ end }} --- -The following is a reference for the XML element and attribute types derived from this model's [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_metaschema.xml). +The following is a reference for the XML element and attribute types derived from this model's [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_metaschema.xml). {{< rawhtml >}} {{ os.ReadFile (printf "%s/%s" (getenv "HUGO_MODEL_DATA_DIR") "xml-definitions.html") }} diff --git a/site/archetypes/complete-reference/xml-index.md b/site/archetypes/complete-reference/xml-index.md index c5122abc6..8d642169e 100644 --- a/site/archetypes/complete-reference/xml-index.md +++ b/site/archetypes/complete-reference/xml-index.md @@ -16,7 +16,7 @@ aliases: The following is an index of each XML element and attribute used in the XML format for this model. Each entry in the index lists all uses of the given element or attribute in the format, which is linked to the corresponding entry in the [XML Format Reference](../xml-reference/). -The combined schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.xsd){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. +The combined schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_schema.xsd){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. Each entry also lists the formal name for the given element or attribute which is linked to the corresponding XML type in the [XML Format Metaschema Reference](../xml-definitions/). {{< rawhtml >}} diff --git a/site/archetypes/complete-reference/xml-outline.md b/site/archetypes/complete-reference/xml-outline.md index f41176d2c..c135fbf21 100644 --- a/site/archetypes/complete-reference/xml-outline.md +++ b/site/archetypes/complete-reference/xml-outline.md @@ -14,7 +14,7 @@ aliases: --- The following outline is a representation of the XML format for the combination of all OSCAL models. -The combined schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.xsd){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. +The combined schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_schema.xsd){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. For each element or attribute, the name links to the corresponding entry in the [XML Format Reference](../xml-reference/). The cardinality and data type are also provided for each element or attribute where appropriate. diff --git a/site/archetypes/model-reference/_index.md b/site/archetypes/model-reference/_index.md index 74fa3dd29..9b1033e6d 100644 --- a/site/archetypes/model-reference/_index.md +++ b/site/archetypes/model-reference/_index.md @@ -23,4 +23,4 @@ The following reference documentation is available for the OSCAL {{ getenv "HUGO - **Outline ([JSON/YAML](json-outline/), [XML](xml-outline/)):** Provides a brief listing of the model's information items organized hierarchically. Useful for understanding the structure and basic syntax of the model in a given format. - **Reference ([JSON/YAML](json-reference/), [XML](xml-reference/)):** Provides a detailed description of the structure and syntax for the model's information items organized hierarchically. Useful for understanding how to use information items within the model in the given format. - **Index ([JSON/YAML](json-index/), [XML](xml-index/)):** Provides a listing of the model's information items organized by where they are used. -- **Definitions ([JSON/YAML](json-definitions/), [XML](xml-definitions/)):** Provides a reference for the XML Schema types and JSON Schema definitions derived from this model's [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}). A metaschema is used to [express the model](https://pages.nist.gov/OSCAL/concepts/layer/overview/#modeling-approach) in a format agnostic way, that is then used to generate the XML and JSON Schema, XML <-> JSON content converters, and this reference documentation. +- **Definitions ([JSON/YAML](json-definitions/), [XML](xml-definitions/)):** Provides a reference for the XML Schema types and JSON Schema definitions derived from this model's [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_metaschema.xml). A metaschema is used to [express the model](https://pages.nist.gov/OSCAL/concepts/layer/overview/#modeling-approach) in a format agnostic way, that is then used to generate the XML and JSON Schema, XML <-> JSON content converters, and this reference documentation. diff --git a/site/archetypes/model-reference/json-definitions.md b/site/archetypes/model-reference/json-definitions.md index b5fae2e27..0c4747844 100644 --- a/site/archetypes/model-reference/json-definitions.md +++ b/site/archetypes/model-reference/json-definitions.md @@ -14,7 +14,7 @@ aliases: {{ end }} --- -The following is a reference for the JSON object definitions derived from the [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}//src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_metaschema.xml) for this [model](https://pages.nist.gov/OSCAL/concepts/layer/{{ getenv "HUGO_LAYER_ID" }}/{{ getenv "HUGO_SCHEMA_ID" }}/). +The following is a reference for the JSON object definitions derived from the [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_metaschema.xml) for this [model](https://pages.nist.gov/OSCAL/concepts/layer/{{ getenv "HUGO_LAYER_ID" }}/{{ getenv "HUGO_SCHEMA_ID" }}/). {{< rawhtml >}} {{ os.ReadFile (printf "%s/%s" (getenv "HUGO_MODEL_DATA_DIR") "json-definitions.html") }} diff --git a/site/archetypes/model-reference/json-index.md b/site/archetypes/model-reference/json-index.md index 82b048827..85307ee91 100644 --- a/site/archetypes/model-reference/json-index.md +++ b/site/archetypes/model-reference/json-index.md @@ -15,7 +15,7 @@ aliases: --- The following is an index of each JSON property used in the JSON format for this [model](https://pages.nist.gov/OSCAL/concepts/layer/{{ getenv "HUGO_LAYER_ID" }}/{{ getenv "HUGO_SCHEMA_ID" }}/), -whose schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.json){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. +whose schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_schema.json){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. Each entry in the index lists all uses of the given property in the format, which is linked to the corresponding entry in the [JSON Format Reference](../json-reference/). Each entry also lists the formal name for the definition which is linked to the corresponding JSON definition in the [JSON Format Metaschema Reference](../json-definitions/). diff --git a/site/archetypes/model-reference/json-outline.md b/site/archetypes/model-reference/json-outline.md index 7f3ee0887..2294082fe 100644 --- a/site/archetypes/model-reference/json-outline.md +++ b/site/archetypes/model-reference/json-outline.md @@ -14,7 +14,7 @@ aliases: --- The following outline is a representation of the JSON format for this [model](https://pages.nist.gov/OSCAL/concepts/layer/{{ getenv "HUGO_LAYER_ID" }}/{{ getenv "HUGO_SCHEMA_ID" }}/), -whose schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.json){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. +whose schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_schema.json){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. For each property, the name links to the corresponding entry in the [JSON Format Reference](../json-reference/). The cardinality and data type are also provided for each property where appropriate. diff --git a/site/archetypes/model-reference/xml-definitions.md b/site/archetypes/model-reference/xml-definitions.md index af0027f8d..11a18af9f 100644 --- a/site/archetypes/model-reference/xml-definitions.md +++ b/site/archetypes/model-reference/xml-definitions.md @@ -14,7 +14,7 @@ aliases: {{ end }} --- -The following is a reference for the XML element and attribute types derived from the [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_metaschema.xml) for this [model](https://pages.nist.gov/OSCAL/concepts/layer/{{ getenv "HUGO_LAYER_ID" }}/{{ getenv "HUGO_SCHEMA_ID" }}/). +The following is a reference for the XML element and attribute types derived from the [metaschema](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/src/metaschema/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_metaschema.xml) for this [model](https://pages.nist.gov/OSCAL/concepts/layer/{{ getenv "HUGO_LAYER_ID" }}/{{ getenv "HUGO_SCHEMA_ID" }}/). {{< rawhtml >}} {{ os.ReadFile (printf "%s/%s" (getenv "HUGO_MODEL_DATA_DIR") "xml-definitions.html") }} diff --git a/site/archetypes/model-reference/xml-index.md b/site/archetypes/model-reference/xml-index.md index aef136887..c6267e407 100644 --- a/site/archetypes/model-reference/xml-index.md +++ b/site/archetypes/model-reference/xml-index.md @@ -15,7 +15,7 @@ aliases: --- The following is an index of each XML element and attribute used in the XML format for this [model](https://pages.nist.gov/OSCAL/concepts/layer/{{ getenv "HUGO_LAYER_ID" }}/{{ getenv "HUGO_SCHEMA_ID" }}/), -whose schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.xsd){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. +whose schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_schema.xsd){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. Each entry in the index lists all uses of the given element or attribute in the format, which is linked to the corresponding entry in the [XML Format Reference](../xml-reference/). Each entry also lists the formal name for the given element or attribute which is linked to the corresponding XML type in the [XML Format Metaschema Reference](../xml-definitions/). diff --git a/site/archetypes/model-reference/xml-outline.md b/site/archetypes/model-reference/xml-outline.md index ac19735b0..e3dc94a01 100644 --- a/site/archetypes/model-reference/xml-outline.md +++ b/site/archetypes/model-reference/xml-outline.md @@ -14,7 +14,7 @@ aliases: --- The following outline is a representation of the XML format for this [model](https://pages.nist.gov/OSCAL/concepts/layer/{{ getenv "HUGO_LAYER_ID" }}/{{ getenv "HUGO_SCHEMA_ID" }}/), -whose schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_SCHEMA_ID" }}_schema.xsd){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. +whose schema can be {{ if eq (getenv "HUGO_REF_TYPE") "tag" }}found [here](https://github.com/usnistgov/OSCAL/releases/download/{{ getenv "HUGO_REF_BRANCH" }}/oscal_{{ getenv "HUGO_MODEL_RAWNAME" }}_schema.xsd){{ else }}built using [the following instructions](https://github.com/usnistgov/OSCAL/blob/{{ getenv "HUGO_REF_BRANCH" }}/build/README.md#artifact-generation){{ end }}. For each element or attribute, the name links to the corresponding entry in the [XML Format Reference](../xml-reference/). The cardinality and data type are also provided for each element or attribute where appropriate. diff --git a/support/generate_modeldoc.sh b/support/generate_modeldoc.sh index 1e38a18c9..e3d49a5d3 100755 --- a/support/generate_modeldoc.sh +++ b/support/generate_modeldoc.sh @@ -134,6 +134,9 @@ do { model_rawname=${model_basename#oscal_} model_rawname=${model_rawname%_metaschema.xml} + # Used to refer to the generated schemas + export HUGO_MODEL_RAWNAME=$model_rawname + # The path to the model relative to the hugo data dir, output dir, and site root model_output_path="models/${REVISION}/${model_rawname}" diff --git a/support/lychee.toml b/support/lychee.toml index ffee45b39..297f527d9 100644 --- a/support/lychee.toml +++ b/support/lychee.toml @@ -3,5 +3,3 @@ exclude_mail = true accept = [200, 206, 429] cache = true - -# format = "markdown" # currently does not exist, must specify --format markdown diff --git a/support/lychee_ignore.txt b/support/lychee_ignore.txt index 260b61e7e..349ba2a54 100644 --- a/support/lychee_ignore.txt +++ b/support/lychee_ignore.txt @@ -13,3 +13,5 @@ https://csrc.nist.gov/projects/cryptographic-module-validation-program/certifica https://cdn.telos.com/wp-content/uploads/2021/06/22150746/Xacta-360-EULA-US.pdf https://search.usa.gov/search https://example.com/.* +https://doi.org/.* +http://doi.org/.* From ff6e80adaf943a51e7cf47195aa05ccc6c107abe Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Mon, 25 Sep 2023 18:47:14 -0400 Subject: [PATCH 06/13] Corrected release notes links --- site/content/models/release-notes.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/site/content/models/release-notes.md b/site/content/models/release-notes.md index 1be5f8c8f..6ab75942c 100644 --- a/site/content/models/release-notes.md +++ b/site/content/models/release-notes.md @@ -45,28 +45,28 @@ The following general changes were made in this release. ### Changes to Profile Model -In /profile/modify/alter ([JSON/YAML](/reference/latest/profile/json-reference/#/profile/modify/alters), [XML](/reference/latest/profile/xml-reference/#/profile/modify/alter)) the following changes were made. See issue [usnistgov/OSCAL#928](https://github.com/usnistgov/OSCAL/issues/928). +In /profile/modify/alter ([JSON/YAML](/models/latest/profile/json-reference/#/profile/modify/alters), [XML](/models/latest/profile/xml-reference/#/profile/modify/alter)) the following changes were made. See issue [usnistgov/OSCAL#928](https://github.com/usnistgov/OSCAL/issues/928). -- The item remove ([JSON/YAML](/reference/latest/profile/json-reference/#/profile/modify/alters/removes), [XML](/reference/latest/profile/xml-reference/#/profile/modify/alter/remove)) has had its child properties/attributes renamed as follows: +- The item remove ([JSON/YAML](/models/latest/profile/json-reference/#/profile/modify/alters/removes), [XML](/models/latest/profile/xml-reference/#/profile/modify/alter/remove)) has had its child properties/attributes renamed as follows: - name-ref -> by-name - class-ref -> by-class - id-ref -> by-id - item-name -> by-item-name - ns-ref -> by-ns -- The item add ([JSON/YAML](/reference/latest/profile/json-reference/#/profile/modify/alters/adds), [XML](/reference/latest/profile/xml-reference/#/profile/modify/alter/add)) has had its child properties/attributes renamed as follows: +- The item add ([JSON/YAML](/models/latest/profile/json-reference/#/profile/modify/alters/adds), [XML](/models/latest/profile/xml-reference/#/profile/modify/alter/add)) has had its child properties/attributes renamed as follows: - id-ref -> by-id ### Changes to System Security Plan Model -In /system-security-plan/control-implementation/implemented-requirement ([JSON/YAML](/reference/latest/system-security-plan/json-reference/#/system-security-plan/control-implementation/implemented-requirements), [XML](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/control-implementation/implemented-requirement)) +In /system-security-plan/control-implementation/implemented-requirement ([JSON/YAML](/models/latest/system-security-plan/json-reference/#/system-security-plan/control-implementation/implemented-requirements), [XML](/models/latest/system-security-plan/xml-reference/#/system-security-plan/control-implementation/implemented-requirement)) -- The item control-id ([JSON/YAML](/reference/latest/system-security-plan/json-reference/#/system-security-plan/control-implementation/implemented-requirements/control-id), [XML](/reference/latest/system-security-plan/xml-reference/#/system-security-plan/control-implementation/implemented-requirement/@control-id)) is now required +- The item control-id ([JSON/YAML](/models/latest/system-security-plan/json-reference/#/system-security-plan/control-implementation/implemented-requirements/control-id), [XML](/models/latest/system-security-plan/xml-reference/#/system-security-plan/control-implementation/implemented-requirement/@control-id)) is now required - In XML the ordering of elements has changed (i.e. responsible-role was moved in the sequence). This change was made to keep the XML element sequencing consistent between this model and the component definition model. ### Changes to Assessment Results Model -- The item findings ([JSON/YAML](/reference/latest/assessment-results/json-reference/#/assessment-results/results/findings), [XML](/reference/latest/assessment-results/xml-reference/#/assessment-results/result/finding)) is now optional. See issue [usnistgov/OSCAL#918](https://github.com/usnistgov/OSCAL/issues/918). +- The item findings ([JSON/YAML](/models/latest/assessment-results/json-reference/#/assessment-results/results/findings), [XML](/models/latest/assessment-results/xml-reference/#/assessment-results/result/finding)) is now optional. See issue [usnistgov/OSCAL#918](https://github.com/usnistgov/OSCAL/issues/918). ## OSCAL 1.0.0 Release Candidate 2 From 9aec2806fcd52053fd5e8db3410587558d8c5dfd Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Mon, 25 Sep 2023 18:55:11 -0400 Subject: [PATCH 07/13] Added aliases to old links and links from bad OSCAL metaschema remarks --- site/.gitignore | 5 +- .../concepts/identifier-use/index.html | 18 + .../assessment/assessment-plan/index.html | 19 + site/content/models/datatypes.md | 704 ------------------ site/content/models/datatypes/index.html | 12 + 5 files changed, 53 insertions(+), 705 deletions(-) create mode 100644 site/content/concepts/identifier-use/index.html create mode 100644 site/content/concepts/layer/assessment/assessment-plan/index.html delete mode 100644 site/content/models/datatypes.md create mode 100644 site/content/models/datatypes/index.html diff --git a/site/.gitignore b/site/.gitignore index 686d553da..c52c618b8 100644 --- a/site/.gitignore +++ b/site/.gitignore @@ -5,4 +5,7 @@ public # all directories here are generated on the fly content/models/*/ data/models/*/ -content/release-assets/latest/* \ No newline at end of file +content/release-assets/latest/* + +# Aliased to Metaschema datatypes page +!content/models/datatypes/ \ No newline at end of file diff --git a/site/content/concepts/identifier-use/index.html b/site/content/concepts/identifier-use/index.html new file mode 100644 index 000000000..f419fce55 --- /dev/null +++ b/site/content/concepts/identifier-use/index.html @@ -0,0 +1,18 @@ + + + + + + + https://pages.nist.gov/OSCAL/resources/concepts/identifier-use/ + + + + + + + \ No newline at end of file diff --git a/site/content/concepts/layer/assessment/assessment-plan/index.html b/site/content/concepts/layer/assessment/assessment-plan/index.html new file mode 100644 index 000000000..c42feadbb --- /dev/null +++ b/site/content/concepts/layer/assessment/assessment-plan/index.html @@ -0,0 +1,19 @@ + + + + + + + https://pages.nist.gov/OSCAL/resources/concepts/layer/assessment/assessment-plan/ + + + + + + + \ No newline at end of file diff --git a/site/content/models/datatypes.md b/site/content/models/datatypes.md deleted file mode 100644 index c3298d66c..000000000 --- a/site/content/models/datatypes.md +++ /dev/null @@ -1,704 +0,0 @@ ---- -title: OSCAL Data Types -heading: Data Types Used in OSCAL -description: A description of the data types used in the OSCAL formats. -weight: 10 -suppressintopiclist: true -sidenav: - title: Data Types -toc: - enabled: true ---- - -The OSCAL models share a set of data type primitives. These data types are documented in the following sections. - -## Simple Data types - -### boolean - -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` | - -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. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "boolean" -} -``` - -### decimal - -A real number expressed using decimal numerals. - -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 - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "number", - "pattern": "(\\+|-)?([0-9]+(\\.[0-9]*)?|\\.[0-9]+)" -} -``` - -### empty - -This data type indicates that the model information element contains no value content, but may contain other structured information elements. - -In XML, this may represent an element without text content. - -In JSON, this may represent an object with labels corresponding to other child information elements, but no label corresponding to a text value. - -**Note: Use of this data type has been *deprecated* with no replacement, since this can be handled with format-specific syntax.** - -### integer - -An integer 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 - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "integer" -} -``` - -### nonNegativeInteger - -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 - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "integer", - "minimum": 0 -} -``` - -### positiveInteger - -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: - -```XML - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "integer", - "minimum": 1 -} -``` - -## Formatted String Data types - -The following are data types based on strings. - -### base64Binary - -A string representing arbitrary Base64-encoded binary data. - -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: - -```XML - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "string", - "pattern": "^[0-9A-Fa-f]+$", - "contentEncoding": "base64" -} -``` - -### date - -This is the same as [date-with-timezone](#date-with-timezone), except the time zone portion is optional. - -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 - - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "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})?$" -} -``` - -### 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. - -For example: - -``` -2019-09-28Z -2019-12-02-08:00 -``` - -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 - - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "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})$" -} -``` - -### dateTime - -This is the same as [dateTime-with-timezone](#datetime-with-timezone), except the time zone portion is optional. - -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 - - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "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)))?$" -} -``` - -### dateTime-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. - -For example: - -``` -2019-09-28T23:20:50.52Z -2019-12-02T16:39:57-08:00 -2019-12-31T23:59:60Z -``` - -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 - - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "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)))$" -} -``` - -### email - -An email address string formatted according to [RFC 6531](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: - -```XML - - - - - Need a better pattern. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "string", - "format": "email", - "pattern": "^.+@.+$" -} -``` - -### 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. - -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 - - - -``` - -**Note: A better pattern is needed for normalizing hostname, since the current data type is very open-ended.** - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "string", - "pattern": "^\\S(.*\\S)?$", - "format": "idn-hostname" -} -``` - -Once a suitable pattern for XML is developed, this pattern will be ported to JSON for more consistent validation. - -### 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. - -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 - - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "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])$" -} -``` - -### 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. - -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 - - - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "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]))$" -} -``` - -### NCName - -A non-colonized name as defined by [XML Schema Part 2: Datatypes Second Edition](https://www.w3.org/TR/xmlschema11-2/#NCName). - -**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 OSCAL revisions that make use of this data type. - -### string - -A string of Unicode characters, but not empty and not whitespace-only (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: - -```XML - - - - - - A trimmed string, at least one character with no leading or - trailing whitespace. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "string", - "pattern": "^\\S(.*\\S)?$" -} -``` - -### token - -A non-colonized name as defined by [XML Schema Part 2: Datatypes Second Edition](https://www.w3.org/TR/xmlschema11-2/#NCName). - -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 - - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "string", - "pattern": "^(\\p{L}|_)(\\p{L}|\\p{N}|[.\\-_])*$" -} -``` - -### uri - -A universal resource identifier (URI) formatted according to [RFC3986](https://tools.ietf.org/html/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 - - - - - Requires a scheme with colon per RFC 3986. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "string", - "format": "uri", - "pattern": "^[a-zA-Z][a-zA-Z0-9+\\-.]+:.+$" -} -``` - -### 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. - -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, at least one character with no leading or - trailing whitespace. - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "type": "string", - "format": "uri-reference" -} -``` - -### uuid - -A version 4 or 5 Universally Unique Identifier (UUID) as defined by [RFC 4122](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 - - - - -``` - -In JSON Schema, this is represented as: - -```JSON -{ - "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}$" -} -``` - -## 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 OSCAL XML-based content using an element set maintained in the OSCAL 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, OSCAL uses a subset of Markdown for use in OSCAL 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. - -The HTML-like syntax supports: - -- HTML paragraphs (`p`), headers (`h1`-`h6`), tables (`table`), preformatted text (`pre`), code blocks (`code`), and ordered and unordered lists (`ol` and `ul`.) - -- Within paragraphs or text content: `a`, `img`, `strong`, `em`, `b`, `i`, `sup`, `sub`. - -In remarks below and throughout this documentation, this element set may be referred to as "prose content" or "prose". This tag set (and Markdown equivalent) is defined as a module. - -Note that elements such as `div`, `blockquote`, `section` or `aside`, used in HTML to provide structure, are *not permitted*. Instead, structures should be represented using specific model elements (or objects in JSON) such as `part`, which can include prose. - -In addition, there are contexts where prose usage may be further constrained. For example, at a higher level (outside the base schema) an application could forbid the use of prose headers `h1-h6` in favor of nested `part` elements with their own titles. - -The Markdown syntax is loosely based on [CommonMark](https://commonmark.org/). When in doubt about Markdown features and syntax, we look to CommonMark for guidance, largely because it is more rigorously tested than many other forms of Markdown. - -### markup-line - -The following table describes the equivalent constructs in HTML and Markdown used within the `markup-line` data type. - -| Markup Type | HTML | Markdown | -|:--- |:--- |:--- | -| Emphasis (preferred) | <em>*text*</em> | \**text*\* -| Emphasis | <i>*text*</i> | \**text*\* -| Important Text (preferred) | <strong>*text*</strong> | \*\**text*\*\* -| Important Text | <b>*text*</b> | \*\**text*\*\* -| Inline code | <code>*text*</code> | \`*text*\` -| Quoted Text | <q>*text*</q> | "*text*" -| Subscript Text | <sub>*text*</sub> | \~*text*\~ -| Superscript Text | <sup>*text*</sup> | ^*text*^ -| Image | <img alt="*alt text*" src="*url*" title="*title text*"/> | !\[*alt text*](*url* "*title text*") -| Link | <a *href*="*url*">*text*</a> | \[*text*](*url*) - -Note: Markdown does not have an equivalent of the HTML <i> and <b> tags, which indicate italics and bold respectively. These concepts are mapped in markup text to <em> and <strong> (see [common mark](https://spec.commonmark.org/0.29/#emphasis-and-strong-emphasis)), which render equivalently in browsers, but do not have exactly the same semantics. While this mapping is imperfect, it represents the common uses of these HTML tags. - -#### Parameter Insertion - -The OSCAL catalog, profile, and implementation layer models allow for control parameters to be defined and injected into prose text. - -Reference injection is handled using the <insert> tag, where you must provide its type and the identifier reference with id-ref: - -```html -This implements as required to address organizational changes. -``` - -The same string in Markdown is represented as follows: - -```markdown -This implements {{ insert: param, pm-9_prm_1 }} as required to address organizational changes. -``` - -#### Specialized Character Mapping - -The following characters have special handling in their HTML and/or Markdown forms. - -| Character | XML HTML | (plain) Markdown | Markdown in JSON | Markdown in YAML | -| --- | --- | --- | --- | --- | -| & (ampersand) | &amp; | & | & | & | -| < (less-than sign or left angle bracket) | &lt; | < | < | < | -| > (greater-than sign or right angle bracket) | > **or** &gt; | > | > | > | -| " (straight double quotation mark) | " **or** &quot; | \\" | \\\\" | \\\\" | -| ' (straight apostrophe) | ' **or** &apos; | \\' | \\\\' | \\\\' | -| \* (asterisk) | \* | \\\* | \\\\\* | \\\\\* | -| ` (grave accent or back tick mark) | ` | \\` | \\\\` | \\\\` | -| ~ (tilde) | ~ | \\~ | \\\\~ | \\\\~ | -| ^ (caret) | ^ | \\^ | \\\\^ | \\\\^ | - -While the characters ``*`~^`` are valid for use unescaped in JSON strings and YAML double quoted strings, these characters have special meaning in Markdown markup. As a result, when these characters appear as literals in a Markdown representation, they must be escaped to avoid them being parsed as Markdown to indicate formatting. The escaped representation indicates these characters are to be represented as characters, not markup, when the Markdown is mapped to HTML. - -Because the character "\\" (back slash or reverse solidus) must be escaped in JSON, note that those characters that require a back slash to escape them in Markdown, such as "\*" (appearing as "\\\*"), must be *double escaped* (as "\\\\\*") to represent the escaped character in JSON or YAML. In conversion, the JSON or YAML processor reduces these to the simple escaped form, again permitting the Markdown processor to recognize them as character contents, not markup. - -Since these characters are not markup delimiters in XML, they are safe to use there without special handling. The XML open markup delimiters "<" and "&", when appearing in XML contents, must as always be escaped as named entities or numeric character references, if they are to be read as literal characters not markup. - -### markup-multiline - -All constructs supported by the [markup-line](#markup-line) data type are also supported by the `markup-multiline` data type, when appearing within a header (`h1`-`h6`), paragraph (`p`), list item (`li`) or table cell (`th` or `td`). - -The following additional constructs are also supported. Note that the syntax for these elements must appear on their own lines (i.e., with additional line feeds as delimiters), as is usual in Markdown. - -| Markup Type | HTML | Markdown | -|:--- |:--- |:--- | -| Heading: Level 1 | <h1>*text*</h1> | # *text* -| Heading: Level 2 | <h2>*text*</h2> | ## *text* -| Heading: Level 3 | <h3>*text*</h3> | ### *text* -| Heading: Level 4 | <h4>*text*</h4> | #### *text* -| Heading: Level 5 | <h5>*text*</h5> | ##### *text* -| Heading: Level 6 | <h6>*text*</h6> | ###### *text* -| Preformatted Text | <pre>*text*</pre> | \`\`\`*text*\`\`\` -| Ordered List, with a single item | <ol><li>*text*</li></ol> | 1. *text* -| Unordered List with single item | <ul><li>*text*</li></ul> | - *text* - -#### Paragraphs - -Additionally, the use of `p` tags in HTML is mapped to Markdown as two double, escaped newlines within a JSON or YAML string (i.e., "\\\\n\\\\n"). This allows Markdown text to be split into paragraphs when this data type is used. - -#### Tables - -Tables are also supported by `markup-multiline` which are mapped from Markdown to HTML as follows: - -- The first row in a Markdown table is considered a header row, with each cell mapped as a <th>. -- The alignment formatting (second) row of the Markdown table is not converted to HTML. Formatting is currently ignored. -- Each remaining row is mapped as a cell using the <td> tag. -- HTML `colspan` and `rowspan` are not supported by Markdown, and so are excluded from use. - -Simple tables are mainly supported due to the prevalence of tables in legacy data sets. However, producers of OSCAL data should note that when they have tabular information, these are frequently semantic structures or matrices that can be described directly in OSCAL as named parts and properties or as parts, sub-parts and paragraphs. This ensures that their nominal or represented semantics are accessible for processing when this information would be lost in plain table cells. Table markup should be used only as a fallback option when stronger semantic labeling is not possible. - -Tables are mapped from HTML to Markdown as follows: - -* Only a single header row <tr><th> is supported. This row is mapped to the Markdown table header, with header cells preceded, delimited, and terminated by `|`. -* The second row is given as a sequence of `---`, as many as the table has columns, delimited by single `|`. In Markdown, a simple syntax here can be used to indicate the alignment of cells; the HTML binding does not support this feature. -* Each subsequent row is mapped to the Markdown table rows, with cells preceded, delimited, and terminated by `|`. - -For example: - -The following HTML table: - -```html - - - -
Col ACol B
Have some ofTry all of
-``` - -Is mapped to the Markdown table: - -```markdown -| Col A | Col B | -| --- | --- | -| Have some of | Try all of | -``` - -#### Line feeds in Markdown - -Additionally, line feed (LF) characters must be escaped as "\\n" when appearing in string contents in JSON and (depending on placement) in YAML. In Markdown, the line feed is used to delimit paragraphs and other block elements, represented using markup (tagging) in the XML version. When transcribed into JSON, these LF characters must also appear as "\\n". diff --git a/site/content/models/datatypes/index.html b/site/content/models/datatypes/index.html new file mode 100644 index 000000000..1b76b9614 --- /dev/null +++ b/site/content/models/datatypes/index.html @@ -0,0 +1,12 @@ + + + + + https://pages.nist.gov/metaschema/specification/datatypes/ + + + + + + + \ No newline at end of file From 09c37bd087b031c61e7de69c5924e5f9f20d5943 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Mon, 25 Sep 2023 18:56:45 -0400 Subject: [PATCH 08/13] Revert inclusion of `$page_base_path` param --- support/generate_modeldoc.sh | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/support/generate_modeldoc.sh b/support/generate_modeldoc.sh index e3d49a5d3..5b5da0b31 100755 --- a/support/generate_modeldoc.sh +++ b/support/generate_modeldoc.sh @@ -143,14 +143,11 @@ do { # The directory Hugo will read the models from relative to the site directory export HUGO_MODEL_DATA_DIR="data/$model_output_path" - # The root of the OSCAL Reference site - page_base_path="OSCAL-Reference/$model_output_path/" - mvn \ --quiet \ -f "${METASCHEMA_DIR}/support/pom.xml" exec:java \ -Dexec.mainClass="com.xmlcalabash.drivers.Main" \ - -Dexec.args="-i source=$model_path page-base-path=$page_base_path output-path=file://${SITE_DIR}/$HUGO_MODEL_DATA_DIR/ ${METASCHEMA_DIR}/src/document/write-hugo-metaschema-docs.xpl" + -Dexec.args="-i source=$model_path output-path=file://${SITE_DIR}/$HUGO_MODEL_DATA_DIR/ ${METASCHEMA_DIR}/src/document/write-hugo-metaschema-docs.xpl" archetype="" model_doc_path="" From 1c9f887db4eb0c059927e81e868da78208a54ee5 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Tue, 26 Sep 2023 09:43:01 -0400 Subject: [PATCH 09/13] Incorporate fix from usnistgov/metaschema-xslt#75 --- support/metaschema-xslt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/support/metaschema-xslt b/support/metaschema-xslt index 66d296599..bd4359a03 160000 --- a/support/metaschema-xslt +++ b/support/metaschema-xslt @@ -1 +1 @@ -Subproject commit 66d2965998431a7ad7f2ea576e27899b52d47a17 +Subproject commit bd4359a0354d3a9452633a8ed915ec9e915d5431 From 2b9f42aea0f212c62eb570a554adcdab02ccf720 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Tue, 26 Sep 2023 09:56:02 -0400 Subject: [PATCH 10/13] Document linkchecker, remove `--cache` option --- README.md | 17 ++++++++++++++++- support/lychee.toml | 2 -- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 246004492..2f8b2ce72 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,22 @@ To see other common operations, refer to the [`Makefile`](./Makefile) or simply ### Local development -The target `make serve` runs builds the site dependencies and runs `hugo serve`. +The target `make serve` runs builds the site and runs `hugo serve`. + +### Link-checking + +This repository uses [Lychee](https://lychee.cli.rs/#/) to crawl the built site for bad external and internal links. +To perform link-checking, run the target `make linkcheck`. +The link checker produces a report, nominally located at `./lychee_report.md`. + +Lychee is configured to ignore URL patterns present in the [`./support/lychee_ignore.txt`](./support/lychee_ignore.txt). + +[Additional configuration](https://lychee.cli.rs/#/usage/cli) can be specified using the Makefile variable `LYCHEE_EXTRA_FLAGS`: + +```sh +# Cache server responses to save bandwidth on repeated runs +make linkcheck LYCHEE_EXTRA_FLAGS='--cache' +``` ### Speeding up the build diff --git a/support/lychee.toml b/support/lychee.toml index 297f527d9..bba50eb1b 100644 --- a/support/lychee.toml +++ b/support/lychee.toml @@ -1,5 +1,3 @@ no_progress = true exclude_mail = true accept = [200, 206, 429] - -cache = true From 27a937e5be5596373c63a53994258aeb816b11fe Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Tue, 26 Sep 2023 10:53:56 -0400 Subject: [PATCH 11/13] Add comment step --- .github/workflows/pages.yaml | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index 59aadbbfc..3e1cbf440 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -11,6 +11,8 @@ on: required: false default: false type: boolean +permissions: + pull-requests: write env: LYCHEE_VERSION: "0.13.0" HUGO_VERSION: "0.118.2" @@ -92,11 +94,18 @@ jobs: - name: Link Check id: linkcheck run: make linkcheck LYCHEE_EXTRA_FLAGS='--github-token ${{ secrets.GITHUB_TOKEN }}' - # TODO - # - name: Comment Broken Links - # uses: marocchino/sticky-pull-request-comment@v2 - # with: - # path: lychee_report.md + - name: Upload linkcheck report + uses: actions/upload-artifact@v3 + with: + name: linkcheck-report + path: lychee_report.md + retention-days: 5 + - name: Comment broken links + uses: marocchino/sticky-pull-request-comment@v2 + with: + path: lychee_report.md + skip_unchanged: true + if: github.event_name == 'pull_request' # # Deployment # From 8ab707d3ca63b34216e934f3d424077cb3626c57 Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Tue, 26 Sep 2023 11:44:40 -0400 Subject: [PATCH 12/13] Make build/linkcheck periodic --- .github/workflows/pages.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pages.yaml b/.github/workflows/pages.yaml index 3e1cbf440..ce83d76d3 100644 --- a/.github/workflows/pages.yaml +++ b/.github/workflows/pages.yaml @@ -11,6 +11,9 @@ on: required: false default: false type: boolean + schedule: + - cron: "0 0 * * MON" + - cron: "0 0 * * THU" permissions: pull-requests: write env: @@ -112,7 +115,8 @@ jobs: - name: Deploy uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # Deploy if on main branch and EITHER the linkcheck succeeds or ignore_linkcheck has been flipped - if: github.ref == 'refs/heads/main' && (steps.linkcheck.outcome == 'success' || github.event.inputs.ignore_linkcheck) + # crucially ignore periodic checks + if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && (steps.linkcheck.outcome == 'success' || github.event.inputs.ignore_linkcheck) with: github_token: ${{ secrets.GITHUB_TOKEN }} enable_jekyll: false From 3ef95acb9a2025518dde123decbff76f40a90d6f Mon Sep 17 00:00:00 2001 From: Nikita Wootten Date: Wed, 27 Sep 2023 12:57:39 -0400 Subject: [PATCH 13/13] Alias release notes page to GitHub --- site/.gitignore | 5 +- site/content/models/release-notes.md | 1086 ------------------ site/content/models/release-notes/index.html | 12 + 3 files changed, 15 insertions(+), 1088 deletions(-) delete mode 100644 site/content/models/release-notes.md create mode 100644 site/content/models/release-notes/index.html diff --git a/site/.gitignore b/site/.gitignore index c52c618b8..16b8a0a02 100644 --- a/site/.gitignore +++ b/site/.gitignore @@ -7,5 +7,6 @@ content/models/*/ data/models/*/ content/release-assets/latest/* -# Aliased to Metaschema datatypes page -!content/models/datatypes/ \ No newline at end of file +# Aliased to other pages +!content/models/datatypes/ +!content/models/release-notes/ diff --git a/site/content/models/release-notes.md b/site/content/models/release-notes.md deleted file mode 100644 index 6ab75942c..000000000 --- a/site/content/models/release-notes.md +++ /dev/null @@ -1,1086 +0,0 @@ ---- -title: OSCAL Release Notes -heading: Release Notes -weight: 15 -suppressintopiclist: true -sidenav: - title: Release Notes -toc: - enabled: true - headingselectors: "h2, h3, h4, h5, h6" ---- - - -Detailed release notes are provided with each OSCAL [release](https://github.com/usnistgov/OSCAL/releases). - -The following are extra release notes for some older OSCAL releases. - -## OSCAL 1.0.0 Release - -The following changes were made in OSCAL 1.0.0 since OSCAL 1.0.0 Release Candidate (RC) 2. - -### Overall changes - -The following general changes were made in this release. - -- In prior releases for some JSON objects, an object's identifier was used as a property. - - For example: - ```json - { - "identifier1": { - "comment": "remainder of object 1" - }, - "identifier2": { - "comment": "remainder of object 2" - } - } - ``` - - While this "BY_KEY" notation does enforce uniqueness of identifiers, this syntax is difficult to write parsers for. This release removes the use of this syntax in favor of a simple array of objects. See issue [usnistgov/OSCAL#914](https://github.com/usnistgov/OSCAL/issues/914). - -- In prior OSCAL releases, the data types used in the OSCAL XML and JSON schemas did not require that provided strings are non-empty (see issue [usnistgov/OSCAL#805](https://github.com/usnistgov/OSCAL/issues/805)), and leading and trailing whitespace was also allowed (see issue [usnistgov/OSCAL#805](https://github.com/usnistgov/OSCAL/issues/805)). Some XML parsers that are schema aware are capable of removing this extra whitespace based on the `whiteSpace="collapse"` schema facet. This only works if the parser is schema aware. To normalize this behavior across all parsers, the OSCAL string data types will now not allow leading and trailing whitespace. - - This led to updates to the string data types in XML and JSON. The `ncname` data type was also replaced by `token` (see issue [usnistgov/OSCAL#911](https://github.com/usnistgov/OSCAL/issues/911)). - -### Changes to Profile Model - -In /profile/modify/alter ([JSON/YAML](/models/latest/profile/json-reference/#/profile/modify/alters), [XML](/models/latest/profile/xml-reference/#/profile/modify/alter)) the following changes were made. See issue [usnistgov/OSCAL#928](https://github.com/usnistgov/OSCAL/issues/928). - -- The item remove ([JSON/YAML](/models/latest/profile/json-reference/#/profile/modify/alters/removes), [XML](/models/latest/profile/xml-reference/#/profile/modify/alter/remove)) has had its child properties/attributes renamed as follows: - - name-ref -> by-name - - class-ref -> by-class - - id-ref -> by-id - - item-name -> by-item-name - - ns-ref -> by-ns - -- The item add ([JSON/YAML](/models/latest/profile/json-reference/#/profile/modify/alters/adds), [XML](/models/latest/profile/xml-reference/#/profile/modify/alter/add)) has had its child properties/attributes renamed as follows: - - id-ref -> by-id - -### Changes to System Security Plan Model - -In /system-security-plan/control-implementation/implemented-requirement ([JSON/YAML](/models/latest/system-security-plan/json-reference/#/system-security-plan/control-implementation/implemented-requirements), [XML](/models/latest/system-security-plan/xml-reference/#/system-security-plan/control-implementation/implemented-requirement)) - -- The item control-id ([JSON/YAML](/models/latest/system-security-plan/json-reference/#/system-security-plan/control-implementation/implemented-requirements/control-id), [XML](/models/latest/system-security-plan/xml-reference/#/system-security-plan/control-implementation/implemented-requirement/@control-id)) is now required -- In XML the ordering of elements has changed (i.e. responsible-role was moved in the sequence). This change was made to keep the XML element sequencing consistent between this model and the component definition model. - -### Changes to Assessment Results Model - -- The item findings ([JSON/YAML](/models/latest/assessment-results/json-reference/#/assessment-results/results/findings), [XML](/models/latest/assessment-results/xml-reference/#/assessment-results/result/finding)) is now optional. See issue [usnistgov/OSCAL#918](https://github.com/usnistgov/OSCAL/issues/918). - -## OSCAL 1.0.0 Release Candidate 2 - -The following changes were made in OSCAL 1.0.0 Release Candidate (RC) 2 since OSCAL 1.0.0 RC 1. - -- Simplification of key OSCAL features - - Properties and annotations have been merged into a single `prop` that now allows an optional `remarks` and `uuid`. - - In the assessment plan and assessment results models, the concepts of a `task` and `action` have been combined. - - Use of `local-definitions` in the assessment plan, assessment results, and POA&M models has been simplified and made more consistent. -- Model documentation improvements - - Some usage descriptions were enhanced to provide more detail and to be more consistent overall. - - Formal names were updated in some places where the names did not match the data element. - - Many spelling errors were corrected. -- Removed the use of XML `` and JSON `additonalProperties` for arbitrary extensions based on community discussion. Extended data can still be provided using `link` declarations to external content. This decision can be revisited in future revisions once there is more implementation experience with the OSCAL models. -- Added the following `link` relations: `latest-version`, `predecessor-version`, and `successor-version` to allow an OSCAL document to link to latest, previous, and next document revisions. -- Fixed a few bugs in the profile resolver code and updated the resolver to work with new profile import/insert structures. -- Provided support for data insertion points for data other than parameters in markup content. - -### Changes common to all models - -- "props" and "annotations" in JSON, and "prop" and "annotation" in XML, have been merged into a single property that now allows an optional `remark` and `uuid`. Semantically, the optional `remark` and `uuid` were the only difference between a "prop" and an "annotation" in OSCAL. The resulting model is simpler with a single construct that will always allow a remark. Names and values that were allowed on annotations are now allowed on properties. -- `latest-version`, `predecessor-version`, and `successor-version` link relations were added to allow an OSCAL document to link to latest, previous, and next document revisions. -- Markup content may now contain data insertion points for data other than parameters. The `insert` object, which may appear in markup content strings, now supports a `type` which can be used to indicate the type of data to insert, and an `id-ref` that identifies the specific data object to take data from. - -### Model-Specific Changes - -#### Catalog and Profile - -- Remarks were added to `param` declarations. -- The import/insert structure in OSCAL profiles has been updated to align with the include/exclude syntax used in the assessment models. This lays the groundwork for more dynamic extension and expansion of include/exclude capabilities in future releases. - -#### Component Definition - -- `set-parameter` was added to `/component-definition/component(s)//control-implementations` to allow for parameter values to be more conveniently defined for all control implementations. - -#### Assessment Plan and Assessment Results - -- The concepts of task and action were combined, resulting in only the concept of a task. A task now has a type, which defines if the task is a "milestone" or "action". This resulted in the following changes: - - `/assessment-results/results/local-definitions/action(s)` was removed. - - `/assessment-results/results/assessment-log/entry/related-action(s)` was removed. - - A task can now define a `dependency` on another task. -- In multiple locations `assessment-subject` has been renamed to `subject` to be more consistent. Before there was a mixture of names. -- In JSON the `/assessment-plan/terms-and-conditions//parts` is always an array. In RC1, if a single part object was provided, the value was a single object. -- In JSON the `/assessment-results/local-definitions/add-objectives-and-methods` was renamed to "objectives-and-methods". Similarly, in XML `/assessment-results/local-definitions/add-objectives-and-methods` was renamed to "objectives-and-methods". -- In JSON and XML `/assessment-results/results/local-definitions/assessment-assets` has been added to allow each result to declare which assessment assets were used during the assessment, if these assets differ from what was defined in the assessment plan. This construct was moved from `/assessment-results/results`. -- In JSON and XML `/assessment-results/results/assessment-subject` has been removed. This was originally used to add subjects that were not found in the assessment plan or SSP. In `/assessment-results/results/local-definitions` you can specify `component(s)`, `inventory-item(s)`, and `user(s)` definitions. These allow the identification of subjects that are not in the assessment plan or SSP, making `assessment-subject` unneeded. -- In `/assessment-results/results/finding` the `collected` and `expires` was removed, since this is an aspect of the observation, not the finding. -- In `/assessment-results/results/finding` the `objective-status` has been replaced by `finding-target` which can now be used to provide a status on a per-subject basis. This allows a finding to be associated with multiple related subjects that might have different states. - -## OSCAL 1.0.0 Release Candidate 1 - -The following changes were made in OSCAL 1.0.0 Release Candidate (RC) 1 since OSCAL 1.0.0 Milestone 3. - -Changes in this release have been focused on the following major areas: -- Making naming in XML and JSON/YAML more consistent. -- Ensuring that all data types and cardinalities are appropriate. -- Refactoring to cleanup models, making them: 1) more consistent with the other OSCAL models, 2) making them more simple when possible, and 3) providing room for future addition of new features. - -### Changes common to all models - -- many elements in XML, and properties in JSON and YAML, have been renamed to make the naming more consistent between elements names in XML and property names in JSON and YAML. Now JSON properties that contain an array of objects use a plural form of the XML element name. The one exception is "prop" in XML vs "properties" in JSON and YAML. This decision was made to make the XML use of "prop" more concise, since "prop" elements are used a good deal in OSCAL XML formats. - -#### Changes to all XML formats - -In {top-level-element}/metadata: -- renamed "revision-history" to "revisions" -- renamed "doc-id" to "document-id" - -In {top-level-element}/metadata/document-id: -- renamed "type" to "scheme" - -In {top-level-element}/metadata/link: -- Defined allowed values for the "rel" property - -In {top-level-element}/metadata/location: -- renamed "email" to "email-address" -- renamed "phone" to "telephone-number" - -In {top-level-element}/metadata/location/prop: -- Defined allowed values for the "name" attribute. Using the "type" as the name attribute value, you can now specify that a location is a "data-center" location and also use the "class" attribute to qualify the data center location as "primary" or "alternate". - -In {top-level-element}/metadata/party: -- renamed "party-name" to "name" -- renamed "email" to "email-address" -- renamed "phone" to "telephone-number" -- changed sequencing of where "address" appears -- made use of address and location-uuid mutually exclusive, since either a static address or a reference to location provides similar functionality. The "location-type" attribute has been removed. This should data should now be described on the referenced "location" element using a prop element with a name of "type". - -In {top-level-element}/metadata/party/prop: -- Defined allowed values for the "name" attribute. This can be used to provide a "mail-stop", "office", or "job-title". - -In {top-level-element}/metadata/party/external-id: -- renamed "type" to "scheme" - -In {top-level-element}/metadata/role: -- renamed "desc" to "description" - -In {top-level-element}/back-matter/resource: -- renamed "desc" to "description" -- renamed "doc-id" to "document-id" - -In {top-level-element}/back-matter/resource/prop: -- defined allowed values "type", "version", and "published" for the "name" property. - -In {top-level-element}/metadata/resource/document-id: -- renamed "type" to "scheme" - -In {top-level-element}/back-matter/resource/rlink: -- changed type from "uri" to "uri-reference" - -Changes to all "prop" elements: -- changed the data type of "ns" to "uri" -- renamed "id" to "uuid" and changed type to "uuid" - -Changes to all "annotation" elements: -- changed the data type of "ns" to "uri" -- renamed "id" to "uuid" and changed type to "uuid" - -#### Changes to all JSON and YAML formats - -In {top-level-object}/metadata: -- renamed "revision-history" to "revisions" -- renamed "properties" to "props" - -In {top-level-object}/metadata/revisions: -- renamed "properties" to "props" - -In {top-level-object}/metadata/document-ids: -- renamed "type" to "scheme" and changed to data type from "string" to "uri" - -In {top-level-object}/metadata/links: -- Defined allowed values for the "rel" property - -In {top-level-object}/metadata/locations -- renamed "URLs" to "urls" -- renamed "properties" to "props" - -In {top-level-object}/metadata/locations/props: -- Defined allowed values for the "name" property. Using the "type" prop name, you can now specify that a location is a "data-center" location and also use the "class" property to qualify the data center location as "primary" or "alternate". - -In {top-level-object}/metadata/parties: -- renamed "party-name" to "name" -- renamed "properties" to "props" -- made use of addresses and location-uuids mutually exclusive, since either a static address or a reference to location provides similar functionality. The "location-type" property on "location-uuid" has been removed. This should data should now be described on the referenced "location" element using a prop element with a name of "type". - -In {top-level-object}/metadata/parties/props: -- defined allowed values for the "name" property. This can be used to provide a "mail-stop", "office", or "job-title". - -In {top-level-object}/metadata/parties/external-ids: -- renamed "type" to "scheme" - -In {top-level-object}/metadata/roles: -- renamed "desc" to "description" -- renamed "properties" to "props" - -In {top-level-object}/back-matter/resources: -- renamed "desc" to "description" -- renamed "properties" to "props" - -In {top-level-object}/back-matter/resources/props: -- defined allowed values "type", "version", and "published" for the "name" property. - -In {top-level-object}/back-matter/resources/citation: -- renamed "properties" to "props" - -In {top-level-object}/back-matter/resources/document-ids: -- renamed "type" to "scheme" and changed to data type from "string" to "uri" - -In {top-level-object}/back-matter/resources/rlinks: -- changed type from "uri" to "uri-reference" - -Changes to all "props" objects: -- changed the data type of "ns" to "uri" - -Changes to all "annotations" objects: -- changed the data type of "ns" to "uri" -- the "value" property is now required. - -Changes to all "address" or "addresses" objects: -- renamed "postal-address" to "addr-lines" - -Changes to all "responsible-party" objects: -- renamed "properties" to "props" - -Changes to all "responsible-role" objects: -- renamed "properties" to "props" -- renamed "party-ids" to "party-uuids" - -### Changes to common to the catalog and profile models - -The following changes have been made to format structures that are shared between the formats for the catalog and profile models. - -#### Changes affecting the catalog and profile XML formats - -Changes to all "part" elements: -- changed the data type of "ns" to "uri" - -Changes to all "param" elements: -- added the "prop" and "link" elements. -- changed the sequencing of where "link" appears to be consistent with other elements that include "link". -- changed the data type of "usage" from "markup-line" to "markup-multiline" -- changed "constraint" from an element with a text value, to an element with child elements. The text value is now contained in the "description" element. Also changed the "test" attribute to be a sequence of child "test" elements, with the text value now contained in the "expression" child element of "test". This structure will allow for more extension going forward. -- changed the cardinality of "value" to allow for multiple values". The data type of a value has changed from markup-line to string. - -#### Changes affecting the catalog and profile JSON and YAML formats - -Changes to all "part" or "parts" objects: -- changed the data type of "ns" to "uri" -- renamed "properties" to "props" -- added allowed values "label" and "sort-id" for props/name. - -Changes to all "param" or "params" objects: -- added the "props" and "links" properties. -- changed the data type of "usage" from "markup-line" to "markup-multiline" -- renamed "guidance" to "guidelines" -- renamed "value" to "values". Also, changed the cardinality of "value" to allow for multiple "values". The data type of a value has changed from markup-line to string. -- changed the sequencing of where "link" appears to align with similar elements in OSCAL. - -For params/select/how-many: -- renamed "alternatives" to "choices" - -For params/select/how-many/alternatives: -- renamed "RICHTEXT" property to "value" - -For params/constraints: -- renamed "detail" to "description". Change the data type from "string" to "markup-multiline". -- renamed "test" to "tests", which is now an array of objects. - - The original "test" string value is now stored in the child object's "expression" property. - - Added a new "remarks" property. - - -### Changes to the catalog model - -The following changes have been made in the XML, JSON, and YAML formats for the OSCAL catalog model. - -#### Changes to the catalog XML format - -For /catalog//group and /catalog//control: -- defined allowed values for prop/@name - -#### Changes to the catalog JSON and YAML formats - -For /catalog, /catalog//groups, and /catalog//controls: -- renamed "parameters" to "params" - -For /catalog//groups and /catalog//controls: -- renamed "properties" to "props" -- defined allowed values for props/name - -### Changes to the profile model - -The following changes have been made in the XML, JSON, and YAML formats for the OSCAL profile model. - -#### Changes to profile XML format - -For /profile/merge/custom//groups: -- added "annotation" and "link" - -For /profile/modify/set-parameter: -- added "prop" and "annotation" -- change sequencing of where "link" appears - -For /profile/modify/alter/add: -- defined allowed values for prop/@name - -#### Changes to profile JSON and YAML formats - -For /profile/imports/(include|exclude): -- renamed "id-selectors" to "calls" -- renamed "pattern-selectors" to "matches" - -For /profile/merge/custom//groups: -- renamed "parameters" to "params" -- renamed "properties" to "props" -- added "annotations" and "links" - -For /profile/modify: -- renamed "parameter-settings" to "set-parameters" -- renamed "alterations" to "alters" - -For /profile/modify/set-parameters: -- added "props" and "annotations" -- renamed "usages" to "usage", and changed data type from an array of "string" to "markup-multiline" - -For /profile/modify/alters: -- renamed "removals" to "removes" -- renamed "additions" to "adds" - -For /profile/modify/alters/adds: -- renamed "parameters" to "params" -- renamed "properties" to "props" -- defined allowed values for props/name - -### Changes to the system security plan (SSP) model - -A number of changes have been made to the SSP model to support the use of leveraged authorizations. Another key change is the use of the "this-system" component to define controls at the system-level. This now means that all SSPs will make use of at least one component. - -The following changes have been made in the XML, JSON, and YAML formats for the OSCAL SSP model. - -#### Changes to the SSP XML format - -For /system-security-plan/system-characteristics: -- added allowed values for prop/@name, annotation/@name, link/@rel, and responsible-roles/role-id - -For /system-security-plan/system-characteristics/*/diagram: -- added "annotation" -- changed the data type of "caption" from "string" to "markup-line" -- added allowed values for link/@rel="diagram", which allows for the linking of an image to use for the diagram. - -For /system-security-plan/system-characteristics/system-information/information-type: -- renamed "id" to "uuid" -- changed structure of "information-type-id" to be wrapped by an outer "categorization", which now defines the "system" for all referenced information type identifiers. -- added "annotation" - -For /system-security-plan/system-characteristics/system-information/information-type/*-impact: -- added "annotation" and "link" - -For /system-security-plan/system-implementation/leveraged-authorization: -- defined additional allowed values "implementation-point", "leveraged-authorization-uuid", "inherited-uuid" for prop/@name, which provides traceability to a leveraged SSP -- defined allowed values for link/@rel - -For /system-security-plan/system-implementation/user: -- defined allowed values for annotation/@name and role-id - -For /system-security-plan/system-implementation/component: -- renamed "component-type" to "type", and updated allowed values -- defined allowed values for prop/@name, annotation/@name, link/@rel, and responsible-role/@role-id - -For /system-security-plan/system-implementation/inventory-item: -- moved "@asset-id" to a required prop/@name -- defined allowed values for prop/@name, annotation/@name, link/@rel, and responsible-role/@role-id - -For /system-security-plan/system-implementation/inventory-item/implemented-component: -- renamed "component-id" to "component-uuid" -- defined allowed values for prop/@name, annotation/@name, and responsible-party/@role-id -- removed "use", since this is capturing similar information to the component's type - -For /system-security-plan/control-implementation/implemented-requirement: -- removed "description" -- added allowed values for annotation/@name including "implementation-status", "control-origination" -- added allowed values for prop/@name including "leveraged-authorization" to indicate if a control implementation is inherited from an underlying authorized system -- added allowed values for responsible-role/$role-id -- changed the sequencing of "set-parameter" and "responsible-role" - -For /system-security-plan/control-implementation/implemented-requirement/by-component: -- renamed "component-id" to "component-uuid" -- added "export", "inherited", and "satisfied" to support documenting leveraged authorizations -- added "remarks" to allow for adding general commentary -- changed the sequencing of where "set-parameter" appears - -For /system-security-plan/control-implementation/implemented-requirement/statement: -- removed "description" - -For /system-security-plan/control-implementation/implemented-requirement/statement/by-component: -- renamed "component-id" to "component-uuid" -- added "export", "inherited", and "satisfied" to support documenting leveraged authorizations -- added "remarks" to allow for adding general commentary -- changed the sequencing of where "set-parameter" appears - -#### Changes to the SSP JSON and YAML formats - -For /system-security-plan/system-characteristics: -- renamed "properties" to "props" -- added allowed values for props/name, annotations/name, links/rel, and responsible-roles/role-id - -For /system-security-plan/system-characteristics/*/diagrams: -- added "annotation" -- changed the data type of "caption" from "string" to "markup-line" -- added allowed values for link/@rel="diagram", which allows for the linking of an image to use for the diagram. - -For /system-security-plan/system-characteristics/system-information: -- renamed "properties" to "props" - -For /system-security-plan/system-characteristics/system-information/information-types: -- renamed "id" to "uuid" -- changed structure of "information-type-ids" to be wrapped by an outer "categorizations", which now defines the "system" for all referenced information type identifiers. -- added "annotations" - -For /system-security-plan/system-characteristics/system-information/information-types/*-impact: -- added "annotations" and "links" - -For /system-security-plan/system-characteristics/authorization-boundary: -- renamed "properties" to "props" - -For /system-security-plan/system-characteristics/network-architecture: -- renamed "properties" to "props" - -For /system-security-plan/system-characteristics/data-flow: -- renamed "properties" to "props" - -For /system-security-plan/system-implementation: -- renamed "properties" to "props" - -For /system-security-plan/system-implementation/leveraged-authorizations: -- defined additional allowed values "implementation-point", "leveraged-authorization-uuid", "inherited-uuid" for prop/name, which provides traceability to a leveraged SSP -- defined allowed values for links/rel - -For /system-security-plan/system-implementation/users: -- defined allowed values for annotation/name and role-id - -For /system-security-plan/system-implementation/components: -- renamed "component-type" to "type", and updated allowed values -- defined allowed values for props/name, annotations/name, links/rel, and responsible-roles/role-id - -For /system-security-plan/system-implementation/inventory-items: -- moved "asset-id" to a required props/name -- defined allowed values for props/name, annotations/name, links/rel, and responsible-parties/role-id - -For /system-security-plan/system-implementation/inventory-items/implemented-components: -- renamed "component-id" to "component-uuid" -- defined allowed values for props/name, annotations/name, and responsible-parties/role-id -- removed "use", since this is capturing similar information to the component's type - -For /system-security-plan/control-implementation/implemented-requirements: -- removed "description" -- renamed "properties" to "props" -- added allowed values for annotations/name including "implementation-status", "control-origination" -- added allowed values for props/name including "leveraged-authorization" to indicate if a control implementation is inherited from an underlying authorized system -- added allowed values for responsible-roles/role-id - -For /system-security-plan/control-implementation/implemented-requirements/by-components: -- renamed "component-id" to "component-uuid" -- added "export", "inherited", and "satisfied" to support documenting leveraged authorizations -- added "remarks" to allow for adding general commentary - -For /system-security-plan/control-implementation/implemented-requirements/statements: -- removed "description" - -For /system-security-plan/control-implementation/implemented-requirements/statements/by-components: -- renamed "component-id" to "component-uuid" -- added "export", "inherited", and "satisfied" to support documenting leveraged authorizations -- added "remarks" to allow for adding general commentary - -### Changes to the component definition model - -Overall, this model was updated to bring the structure of components into alignment with how components are organized in the system security plan model. - -The following changes have been made in the XML, JSON, and YAML formats for the OSCAL component definition model. - -#### Changes to the component definition XML format - -For /component-definition: -- added "uuid" - -For /component-definition/component: -- removed "name" -- changed the data type of "title" from "string" to "markup-line" -- changed the data type of "description" from "string" to "markup-multiline", added a "description" wrapper. -- added "prop" and "annotation" -- changed the sequencing of where "link" appears -- replaced "responsible-party" with "responsible-role" -- added "protocol", which can be used to specify protocol information for a "service" or "network" component -- changed "remarks" adding "remarks" wrapper -- defined allowed values for prop/@name, annotation/@name, link/@rel, and responsible-role/@role-id -- renamed "component-type" to "type", and updated allowed values - -For /component-definition/component/control-implementation: -- changed data type of "uuid" from "string" to "uuid" -- changed the data type of "description" from "string" to "markup-multiline", added a "description" wrapper. - -For /component-definition/component/control-implementation/implemented-requirement: -- changed data type of "uuid" from "string" to "uuid" -- changed the data type of "description" from "string" to "markup-multiline", added a "description" wrapper. - -For /component-definition/capabilities: -- changed the data type of "description" from "string" to "markup-multiline", added a "description" wrapper. -- changed "remarks" adding "remarks" wrapper - -#### Changes to the component definition JSON and YAML formats - -For /component-definition: -- added "uuid" - -For /component-definition/components: -- removed "name" -- changed the data type of "title" from "string" to "markup-line" -- changed the data type of "description" from "string" to "markup-multiline" -- added "props" and "annotations" -- replaced "responsible-parties" with "responsible-roles" -- added "protocols", which can be used to specify protocol information for a "service" or "network" component -- defined allowed values for props/name, annotations/name, links/rel, and responsible-roles/role-id -- renamed "component-type" to "type", and updated allowed values - -For /component-definition/components/control-implementations: -- changed data type of "uuid" from "string" to "uuid" -- changed the data type of "description" from "string" to "markup-multiline" -- renamed "properties" to "props" - -For /component-definition/components/control-implementations/implemented-requirements: -- changed data type of "uuid" from "string" to "uuid" -- changed the data type of "description" from "string" to "markup-multiline" -- renamed "properties" to "props" - -For /component-definition/capabilities: -- changed the data type of "description" from "string" to "markup-multiline" -- renamed "properties" to "props" - -### Refactoring of the assessment and assessment result layer models - -The assessment plan, assessment results, and plan of actions and milestones models have undergone some significant revisions. These revisions have been based on community feedback and a need to provide more extensibility for future growth. Extra review of these models is appreciated as we make preparations for the OSCAL 1.0.0 FINAL release. - -### Changes to the assessment plan model - -Due to the nature of changes in this model, the following documentation details how the new model roughly maps to the older 1.0.0-milestone3 model. The following changes have been made in the XML, JSON, and YAML formats for the OSCAL assessment plan model. - -#### Changes to the assessment plan XML format - -/assessment-plan/local-definitions - -- The structures located in /assessment-plan/assessment-subjects/local-definitions has been moved here. This includes the component, inventory-item, and user element constructions. This allows all content that augments the content from the referenced SSP to be located within a top-level element. -- The "add-objectives-and-methods" element has been added which allow the definitions of new assessment objectives and methods which are to be used in the assessment, but are not located in the catalog for which the system's baseline is generated from. This replaces the original elements located in /assessment-plan/objectives/objective and /assessment-plan/objectives/method. -- The "activity" element has been added to allow an assessment process to be defined. These assessment activities can then be referenced by a specific assessment-action. - -/assessment-plan/terms-and-conditions - -- This new element provides a means to include textual front matter in the assessment plan. This can be used to define rules of engagement, activities to include/exclude from assessments, instructions for delivering results, etc. - -/assessment-plan/reviewed-controls - -- This element includes constructs that previously appeared under /assessment-plan/objectives in the "controls" and "control-objectives" elements. We believe the inclusion/exclusion syntax used now is simpler, more concise, and easier to process. - -/assessment-plan/assessment-subject - -- This element replaces the previous /assessment-plan/assessment-subjects element. -- The old version intermixed included and excluded subjects of different types. -- The new construction pairs includes/excludes of a given type, which should make processing easier and more straightforward. - -/assessment-plan/assessment-assets - -- This new element replaces the previous /assessment-plan/assets element. -- The old element allowed tools to be defined and used "origination" as a way to loosely associate information (e.g., IP addresses used with assessment tools) with these tools. -- The new construction allows for "assessment-platforms" to be identified, which can combine referenced tool components using "uses-component" in multiple combinations providing more control over defining information about tooling used during an assessment. Information that applies to the platform, such as IP addresses used, can be defined using the "prop" element on the "assessment-platform". - -/assessment-plan/assessment-action - -- This new element replaces the /assessment-plan/assessment-activities/test-method element. -- The old element required that information about an assessment process was defined by a "test-method". -- The new construction allows: - - The use of "associated-activity" to reference an "activity" defined under /assessment-plan/local-definitions, which allows the same activity to be used multiple times across different assessment-action elements. - - Use of "assessment-subject" to define in a fine-grained the targeting of subjects the assessment-action are to be performed against. - - Use of the "responsible-role" element to identify assessment roles and optionally parties which are associated with the action. - -/assessment-plan/task - -- This element updates the old element located in /assessment-plan/assessment-activities/schedule/task -- "title" is now required. -- "activity-uuid" is replaced with "related-action". -- "party-uuid" and "location-uuid" is now specified on a per-action basis using the referenced "assessment-action" element's "assessment-subject" entries, which allows both parties and locations to be subjects. -- "compare-to" has been removed, since this was intended to be used in assessment-results only. - -#### Changes to the assessment plan JSON and YAML formats - -/assessment-plan/local-definitions - -- The structures located in /assessment-plan/assessment-subjects/local-definitions has been moved here. This includes the components, inventory-items, and users object constructions. This allows all content that augments the content from the referenced SSP to be located within a top-level element. -- Use of "protocols" has been removed in lieu of defining "network" or "service" components under local-definitions. -- The "add-objectives-and-methods" object array has been added which allow the definitions of new assessment objectives and methods which are to be used in the assessment, but are not located in the catalog for which the system's baseline is generated from. This replaces the original objects located in /assessment-plan/objectives/objectives and /assessment-plan/objectives/method-definitions. -- The "activities" object array has been added to allow an assessment process to be defined. These assessment activities can then be referenced by a specific assessment-action. - -/assessment-plan/terms-and-conditions - -- This new object provides a means to include textual front matter in the assessment plan. This can be used to define rules of engagement, activities to include/exclude from assessments, instructions for delivering results, etc. - -/assessment-plan/reviewed-controls - -- This element includes constructs that previously appeared under /assessment-plan/objectives in the "control-group" and "control-objective-group" object arrays. We believe the inclusion/exclusion syntax used now is simpler, more concise, and easier to process. - -/assessment-plan/assessment-subject - -- This element replaces the previous /assessment-plan/assessment-subjects element. -- The old version intermixed included and excluded subjects of different types. -- The new construction pairs includes/excludes of a given type, which should make processing easier and more straightforward. - -/assessment-plan/assessment-assets - -- This new element replaces the previous /assessment-plan/assets element. -- The old element allowed tools to be defined and used "origination" as a way to loosely associate information (e.g., IP addresses used with assessment tools) with these tools. -- The new construction allows for "assessment-platforms" to be identified, which can combine referenced tool components using "uses-components" in multiple combinations providing more control over defining information about tooling used during an assessment. Information that applies to the platform, such as IP addresses used, can be defined using the "props" object array on an "assessment-platforms" array item object. - -/assessment-plan/assessment-actions - -- This new element replaces the /assessment-plan/assessment-activities/test-methods element. -- The old element required that information about an assessment process was defined by "test-methods". -- The new construction allows: - - The use of "associated-activities" to reference an "activity" defined under /assessment-plan/local-definitions, which allows the same activity to be used multiple times across different assessment-action elements. - - Use of "assessment-subjects" to define in a fine-grained the targeting of subjects the assessment-action are to be performed against. - - Use of the "responsible-roles" to identify assessment roles and optionally parties which are associated with the action. - -/assessment-plan/tasks - -- This element updates the old element located in /assessment-plan/assessment-activities/schedule/tasks -- "title" is now required. -- "activity-uuids" is replaced with "related-actions". -- "party-uuids" and "location-uuids" are now specified on a per-action basis using the referenced "assessment-action" object's "assessment-subjects" array items, which allows both parties and locations to be subjects. -- "compare-to" has been removed, since this was intended to be used in assessment-results only. - - -### Changes to the assessment results model - -Due to the nature of changes in this model, the following documentation details how the new model roughly maps to the older 1.0.0-milestone3 model. The following changes have been made in the XML, JSON, and YAML formats for the OSCAL assessment results model. - -#### Changes to assessment results XML format - -/assessment-results - -- Most of the top-level elements in this model have been relocated under the "result" element or it's children. This allows the assessment details to be specified for each result set. This better supports continuous and evolving assessments. - -/assessment-results/local-definitions - -- The "objective" element relocates and updates the old element in /assessment-results/objectives/objective allowing new assessment objectives to be defined that were not defined in the catalog supporting the system's baseline or the assessment plan. -- The new "activity" element is similar to the related one in the assessment plan, and allows an assessment process to be defined. These assessment activities can then be referenced by a specific assessment-action. - -/assessment-results/results/local-definitions - -- The structures located in /assessment-results/assessment-subjects/local-definitions has been moved here. This includes the "component", "inventory-item", and "user" element constructions. This allows all content that augments the content from the referenced SSP to be located within a top-level element. -- The "add-objectives-and-methods" element has been added which allow the definitions of new assessment objectives and methods which are to be used in the assessment, but are not located in the catalog for which the system's baseline is generated from. This replaces the original elements located in /assessment-results/objectives/objective and /assessment-results/objectives/method. -/assessment-results/results/assessment-actions -- The "assessment-action" element replaces the /assessment-plan/assessment-activities/test-methods element. - - The old element required that information about an assessment process was defined by "test-methods". This structure was moved to local-definitions, since this is adding to the actions defined in the assessment plan. - - The new construction allows: - - The use of "associated-activities" to reference an "activity" defined under /assessment-plan/local-definitions, which allows the same activity to be used multiple times across different assessment-action elements. - - Use of "assessment-subjects" to define in a fine-grained the targeting of subjects the assessment-action are to be performed against. - - Use of the "responsible-roles" to identify assessment roles and optionally parties which are associated with the action. - -/assessment-results/results/reviewed-controls - -- This element includes constructs that previously appeared under /assessment-results/objectives in the "controls" and "control-objectives" elements. We believe the inclusion/exclusion syntax used now is simpler, more concise, and easier to process. - -/assessment-results/results/assessment-subject - -- This element replaces the previous /assessment-results/assessment-subjects element. -- The old version intermixed included and excluded subjects of different types. -- The new construction pairs includes/excludes of a given type, which should make processing easier and more straightforward. - -/assessment-results/results/assessment-assets - -- This new element replaces the previous /assessment-results/assets element. -- The old element allowed tools to be defined and used "origination" as a way to loosely associate information (e.g., IP addresses used with assessment tools) with these tools. -- The new construction allows for "assessment-platforms" to be identified, which can combine referenced tool components using "uses-components" in multiple combinations providing more control over defining information about tooling used during an assessment. Information that applies to the platform, such as IP addresses used, can be defined using the "props" object array on an "assessment-platforms" array item object. - -/assessment-results/results/attestation - -- This new element allows for arbitrary statements to be made in the assessment results. - -/assessment-results/results/assessment-log - -- This new element implements the functionality previously supported by the /assessment-results/assessment-activities/schedule/tasks element, but in a refactored way. -- An "entry" can be used to log any event that occurs during an assessment. - - An "entry" can be associated with an action or a task. An action is a concrete activity that is performed during an assessment, while a task is a high-level scheduled event used for project management that may be associated with multiple actions. The two can be used together to detail the work accomplished during the assessment. - - The "related-action" element can associate the log entry with an action declared in the plan or the results to record progress on or completion of the action. The "related-action" can be used to assign a "responsible-party" and can also be associated with an "assessment-subject". - - The "related-task" element can associate the log entry with a task declared in the plan to record progress on or completion of the task. The "related-task" can be used to assign a "responsible-party" and can also be associated with an "assessment-subject". - - "title" is now required. - - "activity-uuids" is replaced with "related-actions". - - "party-uuids" and "location-uuids" are now specified on a per-action basis using the referenced "assessment-action" object's "assessment-subjects" array items, which allows both parties and locations to be subjects. - -/assessment-results/results/observation - -- This element updates the old element located in /assessment-results/results/finding/observation. Observations have been separated out from findings to allow a given observation to be linked to by many findings and risks. -- renamed "observation-method" to "method" -- renamed "observation-type" to "type" -- "assessor" has been replaced with "origin", which allows the tool, assessment-platform, and/or any parties to be identified as one or more "actor" elements. The related action and/or task can also be associated here using "related-action" and "related-task". - -/assessment-results/results/risk - -- This element updates the old element located in /assessment-results/results/finding/risk. Risks have been separated out from findings to allow a given risk to be linked to by many findings. -- Renamed "risk-status" to "status" -- The new "origin" element can be used to describe the tool or party that generated the risk record. -- Replaced "risk-metric" with "characterization", which allows any risk characteristic to be as a "facet". The specific tool, assessment-platform, and/or any parties producing a characterization can be identified using one or more "actor" elements. The related action and/or task can also be associated here using "related-action" and "related-task". -- All remediation related contents has been moved to "response", which will be discussed below. -- A "risk-log/entry" can be used to identify any action that relates to the assessment of or handling of a risk. This replaces the "/assessment-results/results/risk/remediation-tracking", while proving more robust capabilities. -- "party-id" has been replaced with identifying the party as an actor under "origin". - -/assessment-results/results/risk/response - -- This new element realigns all of the risk/remediation information in a way that supports other risk response activities in addition to remediation. -- "origin" allows the tool, assessment-platform, and/or party identifying the response to be identified, replacing /assessment-results/results/risk/remediation-origin. -- "task" is used to define a schedule of events replacing /assessment-results/results/risk/remediation-deadline and /assessment-results/results/risk/remediation/schedule/task. This allows risk responses to be defined in a more fine-grained way. -- Renamed "required" to "required-asset" - -/assessment-results/results/finding - -- This element maps to the same element in the old model. -- Moved the embedded "observation" and "risk" elements to "related-observation" and "associated-risk" references. - -#### Changes to assessment results JSON and YAML formats - -/assessment-results - -- Most of the top-level properties in this model have been relocated under the "results" property or it's child objects. This allows the assessment details to be specified for each result set. This better supports continuous and evolving assessments. - -/assessment-results/local-definitions - -- The "objectives" object array relocates and updates the old object array in /assessment-results/objectives/objectives allowing new assessment objectives to be defined that were not defined in the catalog supporting the system's baseline or the assessment plan. -- The new "activities" object array is similar to the related one in the assessment plan, and allows an assessment process to be defined. These assessment activities can then be referenced by a specific assessment-action. - -/assessment-results/results/local-definitions - -- The structures located in /assessment-results/assessment-subjects/local-definitions has been moved here. This includes the "components", "inventory-items", and "users" property constructions. This allows all content that augments the content from the referenced SSP to be located within a top-level property. -- The "add-objectives-and-methods" property has been added which allow the definitions of new assessment objectives and methods which are to be used in the assessment, but are not located in the catalog for which the system's baseline is generated from. This replaces the original properties located in /assessment-results/objectives/objectives and /assessment-results/objectives/methods. -/assessment-results/results/assessment-actions -- The "assessment-action" property replaces the /assessment-plan/assessment-activities/test-methods property. - - The old property required that information about an assessment process was defined by "method-definitions". This structure was moved to local-definitions, since this is adding to the actions defined in the assessment plan. - - The new construction allows: - - The use of "associated-activities" to reference an "activity" defined under /assessment-plan/local-definitions, which allows the same activity to be used multiple times across different assessment-action properties. - - Use of "assessment-subjects" to define in a fine-grained the targeting of subjects the assessment-action are to be performed against. - - Use of the "responsible-roles" to identify assessment roles and optionally parties which are associated with the action. - -/assessment-results/results/reviewed-controls - -- This property includes constructs that previously appeared under /assessment-results/objectives in the "controls_group" and "control-objectives_group" properties. We believe the inclusion/exclusion syntax used now is simpler, more concise, and easier to process. - -/assessment-results/results/assessment-subjects - -- This property replaces the previous /assessment-results/assessment-subjects property. -- The old version intermixed included and excluded subjects of different types. -- The new construction pairs includes/excludes of a given type, which should make processing easier and more straightforward. - -/assessment-results/results/assessment-assets - -- This new property replaces the previous /assessment-results/assets property. -- The old property allowed tools to be defined and used "origination" as a way to loosely associate information (e.g., IP addresses used with assessment tools) with these tools. -- The new construction allows for "assessment-platforms" to be identified, which can combine referenced tool components using "uses-components" in multiple combinations providing more control over defining information about tooling used during an assessment. Information that applies to the platform, such as IP addresses used, can be defined using the "props" object array on an "assessment-platforms" array item object. - -/assessment-results/results/attestations - -- This new property allows for arbitrary statements to be made in the assessment results. - -/assessment-results/results/assessment-log - -- This new property implements the functionality previously supported by the /assessment-results/assessment-activities/schedule/tasks property, but in a refactored way. -- An "entry" can be used to log any event that occurs during an assessment. - - An "entry" can be associated with an action or a task. An action is a concrete activity that is performed during an assessment, while a task is a high-level scheduled event used for project management that may be associated with multiple actions. The two can be used together to detail the work accomplished during the assessment. - - The "related-actions" property can associate the log entry with an action declared in the plan or the results to record progress on or completion of the action. The "related-action" can be used to assign a "responsible-party" and can also be associated with an "assessment-subject". - - The "related-tasks" property can associate the log entry with a task declared in the plan to record progress on or completion of the task. The "related-task" can be used to assign a "responsible-party" and can also be associated with an "assessment-subject". - - "title" is now required. - - "activity-uuids" is replaced with "related-actions". - - "party-uuids" and "location-uuids" are now specified on a per-action basis using the referenced "assessment-action" object's "assessment-subjects" array items, which allows both parties and locations to be subjects. - -/assessment-results/results/observation - -- This property updates the old property located in /assessment-results/results_group/findings/observations. Observations have been separated out from findings to allow a given observation to be linked to by many findings and risks. -- renamed "observation-method" to "method" -- renamed "observation-type" to "type" -- "assessor" has been replaced with "origin", which allows the tool, assessment-platform, and/or any parties to be identified as one or more "actor" properties. The related action and/or task can also be associated here using "related-action" and "related-task". - -/assessment-results/results/risks - -- This property updates the old property located in /assessment-results/results_group/findings/risks. Risks have been separated out from findings to allow a given risk to be linked to by many findings. -- Renamed "risk-status" to "status" -- The new "origin" property can be used to describe the tool or party that generated the risk record. -- Replaced "risk-metric" with "characterization", which allows any risk characteristic to be as a "facet". The specific tool, assessment-platform, and/or any parties producing a characterization can be identified using one or more "actor" properties. The related action and/or task can also be associated here using "related-action" and "related-task". -- All remediation related contents has been moved to "response", which will be discussed below. -- A "risk-log/entry" can be used to identify any action that relates to the assessment of or handling of a risk. This replaces the "/assessment-results/results_group/risks/remediation-tracking" and "/assessment-results/results_group/risks/closure-actions", while proving more robust capabilities. -- "party-ids" has been replaced with identifying the party as an actor under "origin". - -/assessment-results/results/risks/responses - -- This new property realigns all of the risk/remediation information in a way that supports other risk response activities in addition to remediation. -- "origin" allows the tool, assessment-platform, and/or party identifying the response to be identified, replacing /assessment-results/results_group/risks/remediation-group/origins. -- "task" is used to define a schedule of events replacing /assessment-results/results_group/risks/remediation-deadline and /assessment-results/results_group/risks/remediation-group/schedule/tasks. This allows risk responses to be defined in a more fine-grained way. -- Renamed "required" to "required-asset" - -/assessment-results/results/findings - -- This property maps to the same property in the old model. -- Moved the embedded "observation" and "risk" properties to "related-observation" and "associated-risk" references. - -### Changes to the plan of actions and milestones (PO&M) model - -Due to the nature of changes in this model, the following documentation details how the new model roughly maps to the older 1.0.0-milestone3 model. The following changes have been made in the XML, JSON, and YAML formats for the OSCAL PO&M model. - -#### Changes to the plan of actions and milestones XML formats - -- The PO&M XML format has been updated to align with the assessment results XML format. Most of the changes in the previous section related to assessment results apply here. - -/plan-of-action-and-milestones/poam-item - -- Like the assessment results, the "poam-item" now has the "observation" and "risk" elements broken out as siblings and references to these elements are used instead. -- Removed "objective-status" and "implementation-status-uuid, since this was added here by mistake and is covered in the assessment results. - -#### Changes to the plan of actions and milestones JSON and YAML formats - -- The PO&M JSON and YAML format has been updated to align with the assessment results JSON and YAML format. Most of the changes in the previous section related to assessment results apply here. - -/plan-of-action-and-milestones/poam-items - -- Replaces /plan-of-action-and-milestones/poam-items/poam-item-group -- Like the assessment results, the "poam-items" now has the "observation" and "risk" elements broken out as siblings and references to these objects are used instead. -- Removed "objective-status" and "implementation-status-uuid, since this was added here by mistake and is covered in the assessment results. - -## OSCAL 1.0.0 Milestone 3 --- - -### New OSCAL models - -The following new models have been added to OSCAL. - -- Component Definition model: Allows for the definition of a set of *components* that each provide a description of the controls supported by a specific implementation of a hardware, software, or service; or by a given policy, process, procedure, or compliance artifact (e.g., FIPS 140-2 validation). -- Assessment Plan model: Represents the planning for a periodic or continuous assessment. -- Assessment Results model: Represents the findings of a periodic or continuous assessment of a specific system. -- Plan of Action and Milestones (POA&M) model: Represents the known risks for a specific system, as well as the identified deviations, remediation plan, and disposition status of each risk. - -### Changes to all Models - -#### Changing 'name' flag to 'title' field - -On several assemblies, what had been represented with a 'name' flag is now represented with a 'title' field, which permits inline markup. - -'title' now appears in these assemblies: 'metadata', 'revision', 'location', 'resource', 'role', 'information-type', 'leveraged-authorization', 'user', 'authorized-privilege', 'component', and 'protocol'. - -#### Changes of ID to UUID - -A number of assemblies that used to carry 'id' flags now carry 'uuid' flags instead. These include (in the SSP model) : 'location', 'party', 'resource', 'diagram', 'user', 'component', 'protocol', 'inventory-item', 'implemented-requirement', 'statement', and 'by-component'. In all models, it includes 'location', 'party', and 'resource'. Finally, the full assemblies 'catalog', 'profile' and 'system-security-plan' fall into this category. - -Similarly, flags and fields that are named to indicate they provide a point of reference, are now renamed '-uuid' reflecting when their references is given specifically as a 'uuid' (and validated as such) not as an 'id'. These include 'location-uuid' and 'party-uuid'. - -#### 'metadata' changes - -Milestone 3 has two assemblies in the metadata, revision for tracking a revision history, and location, an abstraction (and alternative) to the older address modeling. - -[M2] model: title (field), published? (field), last-modified (field), version (field), oscal-version (field), doc-id* (field), prop* (field), link* (field), role* (assembly), party* (assembly), responsible-party* (assembly), remarks? (field) - -[M3] model: title (field), published? (field), last-modified (field), version (field), oscal-version (field), revision* (assembly), doc-id* (field), prop* (field), link* (field), role* (assembly), location* (assembly), party* (assembly), responsible-party* (assembly), remarks? (field) - -##### New 'revision' assembly: Revision History Entry (all models) - -Tracking revisions can now be done by capturing a snapshot of metadata at an earlier point, potentially with properties or remarks added to indicate revision status or purpose. - -[M3] model: title? (field), published? (field), last-modified? (field), version? (field), oscal-version? (field), prop* (field), link* (field), remarks? (field) - -##### New 'location' assembly: Location (all models) - -A new assembly permits factoring out geographic or contact information (an address or contact point) into a separate data structure, for reference using its 'uuid' flag. - -[M3] model: title? (field), address (assembly), email* (field), phone* (field), url* (field), prop* (field), annotation* (assembly), link* (field), remarks? (field) - -##### New 'location-uuid': Location Reference - -##### 'party' changes (all models) - -'party' is for Party (organization or person). It has been refactored to reflect the (somewhat arbitrary) 'organization' vs 'person' distinction into a 'type' flag. - -Where before, we had an 'id' flag, now we have 'uuid'. We also have 'type', a flag whose value can capture "person" or "organization". - -We also have new fields for linking to other assemblies, including 'member-of-organization'. Instead of 'org-name' and 'person-name' we simply have 'party-name'. - -[M2] flags: id? - -[M3] flags: uuid?, type? - -[M2] model: person* (assembly), org? (assembly), prop* (field), annotation* (assembly), link* (field), remarks? (field) - -[M3] model: party-name (field), short-name? (field), external-id* (field), prop* (field), annotation* (assembly), link* (field), address* (assembly), email* (field), phone* (field), member-of-organization (field), location-uuid (field)**, remarks? (field) - -##### New field 'party-uuid': Party Reference - -Replaces 'person/id' and 'org/id' from the M2 model. - -##### New field 'external-id': Personal Identifier - -Replaces 'party-id' and 'org-id' from the M2 model. - -##### New field 'member-of-organization': Organizational Affiliation - -Used to associate a person or organization with another organization. This can be used to create organization hierarchies. - -##### New field 'party-name': Party Name - -Replaces 'org-name' and 'person-name' from the M2 model. - -#### 'back-matter' changes - -In the back matter, the old 'citation' element has been refactored as a special case of 'resource'. - -[M2] model: citation* (assembly), resource* (assembly) - -[M3] model: resource* (assembly) - -##### Refactored 'resource': Resource - -The old 'citation' assembly is now a child, not a sibling of resource within 'back-matter'. As such it has been remodeled to support as much specialized citation information as may be available for a resource. - -[M2] flag: id? - -[M3] flags: uuid? - -[M2] model: desc? (field), prop* (field), (A choice: rlink* (assembly), base64? (field) ) , remarks? (field) - -[M3] model: title? (field), desc? (field), prop* (field), doc-id* (field), citation? (assembly), rlink* (assembly), base64* (field), remarks? (field), (any) - -New assemblies and fields to support the citation model. - -##### New field 'text': Biblographic Text - -A plain-text capture of a bibliographic citation. - -##### New assembly 'biblio': Bibliographic Definition - -A structured representation of a bibliographic resource (an extension point). - -##### 'citation' changes - -A 'citation' now appears only as a child of a 'resource'. - -[M2] flag: id? - -[M3] flag: [none] - -[M2] model: target* (field), title? (field), desc? (field), doc-id* (field), prop* (field), ? (any) - -[M3] model: text (field), prop* (field), biblio? (assembly) - - -### Changes to the Profile Model - -#### Change to 'add': Addition (profile model) - -A new 'id-ref' flag permits targeting an addition to a particular object (branch) within the structure addressed for addition. Additionally, an 'annotation' element may also be added. - -[M2] flag: position? - -[M3] flags: position?, id-ref? - -[M2] model: title? (field), param* (assembly), prop* (field), link* (field), part* (assembly) - -[M3] model: title? (field), param* (assembly), prop* (field), annotation* (assembly), link* (field), part* (assembly) - -### Changes to the System Security Plan (SSP) Model - -#### 'system-implementation' changes - -An assembly for 'leveraged-authorization' has been added. 'leveraged-authorization' used to be in 'system-characteristics'. - -[M2] model: prop* (field), annotation* (assembly), link* (field), user* (assembly), component* (assembly), service* (assembly), interconnection* (assembly), system-inventory? (assembly), remarks? (field) - -[M3] model: prop* (field), annotation* (assembly), link* (field), leveraged-authorization* (assembly), user* (assembly), component* (assembly), system-inventory? (assembly), remarks? (field) - -#### 'component' changes - -The component assembly has been remodeled to permit greater generality and expressiveness. New assemblies include 'title', 'purpose', and 'protocol'. - -[M2] flags: id?, name?, component-type? - -[M3] flags: uuid?, component-type? - -[M2] model: description (field), prop* (field), annotation* (assembly), link* (field), status (assembly), responsible-role* (assembly), remarks? (field) - -[M3] model: title (field), description (field), purpose? (field), prop* (field), annotation* (assembly), link* (field), status (assembly), responsible-role* (assembly), protocol* (assembly), remarks? (field) - -#### Rename 'set-param' to 'set-parameter' - -In profile SSP models, the assembly used to set a parameter is consistently called 'set-parameter'. - -## OSCAL 1.0.0 Milestone 2 - -### New OSCAL Features - -- A System Security Plan (SSP) model has been added to OSCAL for use by organizations to document the implementation of security and privacy controls in an information system. - -### Breaking Changes - -The following content model changes have been made to the catalog and profile models that may break content compatibility: - -#### Document metadata - - * `last-modified` is now required. Its value must be a date-time with time zone (i.e., a timestamp). The old element `last-modified-date` is no longer permitted. - * `published` is permitted for a nominal publication date, as assigned by the owner or publisher of the catalog or resource. An electronic version of a previously published catalog should carry its own publication date, if any, not that of the original resource (which can be described elsewhere with its own metadata). - * `role-id` is now assigned as an element in the XML, not an attribute. This permits it to be tokenized more explicitly. - -#### Control structures in the catalog model - -##### New property in SP800-53 catalog data - -In the SP800-53 catalog, we have added a property called `sort-id` to controls and enhancements. Its string value represents the control's ID in a (zero-padded) notation that will sort gracefully against other `sort-id` values. This permits a robust reordering of controls in receiving systems without having to refer to an out-of-line document to restore the canonical order. - -##### Controls inside controls, but no "subcontrols" - -Control enhancements are now represented using `control` not `subcontrol`. The advantages of restricting to two levels of hierarchy (even given groups and parts) became too few in view of the sacrifices to expressiveness so we have gone back to clean recursion. - -#### Data type handling - -Data type handling has been extended in several respects to provide for the validating of lexical forms of nominal datatypes. Datatypes for dates and times have been added. Several XML-peculiar datatypes have been removed. - -##### Value enumeration on terminal nodes - -The schema has also been extended to support validation against enumerated values, either exclusively (only declared values may appear) or inclusively (enumerations are documented while other values are also permitted). All allowed values now being declared (Milestone 2) are inclusive of other values (user- or application-defined), so this is not a breaking change. - -Affected data points (in both models): `prop/name`, `address/type`, `phone/type`, `hash/algorithm`, `role-id`. The enumerated values provided for each are documented. - -##### Lexical datatyping at points - -Supported for lexical datatyping has also been added to `link/href`, `rlink/href` (URI references), `published` and `last-modified` (timestamps), `email` (a nominal email address), `url` (a URI), `img/src`. - -#### Profile model enhancements - -##### Calling control enhancements (old "subcontrols") - -From call statements, since `subcontrol` has been dropped from the catalog model, `subcontrol-id` has been replaced with `control-id`, and `with-subcontrols` has been replaced by `with-child-controls` (on `call`, `all` and `match`). Essentially, a subcontrol is now represented as a control that is a child another parent control. - -##### Expanded model for new groups - -Elements besides control references are now permitted inside `group` within the `merge` construct, so profile authors can provide titles and introductory content to groups they define for their represented aggregate control structures. - -##### Parameter settings - -Added 'guideline' to profile model. It was omitted in error. - -See issues #494, #288 (adding 'guideline' to profile model) - - -## OSCAL 1.0.0 Milestone 1 --- - -- The first official OSCAL release -- Provides stable versions of the OSCAL catalog and profile models in XML and JSON formats, along with associated XML and JSON schemas. -- Includes draft versions of the NIST SP 800-53 revision 4 OSCAL content and FedRAMP baselines in OSCAL XML, JSON, and YAML formats. -- Provides content converters that are capable of accurately converting between OSCAL catalog and profile content in OSCAL XML to OSCAL JSON format and vice versa. diff --git a/site/content/models/release-notes/index.html b/site/content/models/release-notes/index.html new file mode 100644 index 000000000..1076ccd93 --- /dev/null +++ b/site/content/models/release-notes/index.html @@ -0,0 +1,12 @@ + + + + + https://github.com/usnistgov/OSCAL/releases + + + + + + + \ No newline at end of file