From 0e50693943152f509ab3fda259828eabb3c4123a Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Mon, 9 Feb 2026 23:37:19 -0500 Subject: [PATCH] feat: replace XSLT-based build system with oscal-cli Replace the metaschema-xslt toolchain and Maven/Saxon infrastructure with oscal-cli-enhanced for all schema generation and validation tasks. Build system changes: - Add oscal-cli auto-install that checks PATH first, downloads from Maven Central to build/bin/ if not found - Replace XSLT-based schema generation with oscal-cli metaschema generate-schema for both JSON Schema and XSD output - Replace schematron composition validation with oscal-cli metaschema validate - Remove XSLT converter generation (oscal-cli provides direct content conversion) - Remove resolved metaschema generation (no longer needed) - Update archive generation to include schemas and source metaschemas - Make xmllint optional for environments without it - Move link checking to end of build pipeline Dependency removal: - Remove metaschema-xslt submodule and nested schxslt submodule - Remove Maven pom.xml, resolve-entities.xsl, and xslt-runner.sh - Remove Java setup from CI/CD status workflow Documentation: - Update build README with oscal-cli prerequisites and usage - Replace XSLT converter documentation with oscal-cli content conversion examples - Update release README to reflect new archive structure --- .gitignore | 7 ++ .gitmodules | 9 --- build/.gitignore | 4 -- build/Makefile | 124 +++++++++++++-------------------- build/README.md | 97 +++++++------------------- build/metaschema-xslt | 1 - build/pom.xml | 65 ----------------- build/resolve-entities.xsl | 60 ---------------- build/xslt-runner.sh | 38 ---------- build/xspec | 1 - src/release/release-readme.txt | 11 +-- 11 files changed, 88 insertions(+), 329 deletions(-) delete mode 100644 build/.gitignore delete mode 160000 build/metaschema-xslt delete mode 100644 build/pom.xml delete mode 100644 build/resolve-entities.xsl delete mode 100755 build/xslt-runner.sh delete mode 160000 build/xspec diff --git a/.gitignore b/.gitignore index bc48dcc7c9..115c0540d2 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ backup* working/ __pycache__ xspec/ +.worktrees/ # test reports testing/*.html @@ -50,6 +51,12 @@ target/ # node_modules/ +# Build outputs +/build/generated*/ +/build/out/ +# Auto-downloaded oscal-cli +/build/bin/ + # Files build by CI/CD /docs/content/documentation/specification/processing/profile-resolution.html /docs/scratch-dir diff --git a/.gitmodules b/.gitmodules index 46afc99b3d..e69de29bb2 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,9 +0,0 @@ -[submodule "build/metaschema-xslt"] - path = build/metaschema-xslt - url = https://github.com/usnistgov/metaschema-xslt.git -[submodule "build/metaschema-xslt/support/schxslt"] - path = build/metaschema-xslt/support/schxslt - url = https://codeberg.org/SchXslt/schxslt.git -[submodule "build/xspec"] - path = build/xspec - url = https://github.com/xspec/xspec.git diff --git a/build/.gitignore b/build/.gitignore deleted file mode 100644 index 86a2f1382f..0000000000 --- a/build/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -/node_modules/ -# Ignore all variations of generated_* directories -/generated*/ -/out/ \ No newline at end of file diff --git a/build/Makefile b/build/Makefile index b55b648b07..22633a047a 100644 --- a/build/Makefile +++ b/build/Makefile @@ -14,10 +14,10 @@ help: ## Show this help message all: artifacts checks archives ## Run all pipelines .PHONY: artifacts -artifacts: schemas converters resolved-metaschemas ## Generate all artifacts +artifacts: schemas ## Generate all artifacts .PHONY: checks -checks: linkcheck validate test-profile-resolution ## Run all tests and checks +checks: validate linkcheck ## Run all tests and checks .PHONY: dependencies dependencies: node_modules ## Ensure dependencies have been installed @@ -26,9 +26,36 @@ node_modules: package.json package-lock.json npm ci .PHONY: clean -clean: clean-schemas clean-linkcheck clean-converters clean-archives clean-resolved-metaschemas ## Remove all generated content +clean: clean-schemas clean-linkcheck clean-archives ## Remove all generated content + +# oscal-cli configuration +OSCAL_CLI_VERSION:=3.1.0 +OSCAL_CLI_DOWNLOAD_URL:=https://repo1.maven.org/maven2/dev/metaschema/oscal/oscal-cli-enhanced/$(OSCAL_CLI_VERSION)/oscal-cli-enhanced-$(OSCAL_CLI_VERSION)-oscal-cli.tar.bz2 +OSCAL_CLI_DIR:=bin/oscal-cli +OSCAL_CLI_ARCHIVE:=$(OSCAL_CLI_DIR)/oscal-cli-enhanced-$(OSCAL_CLI_VERSION)-oscal-cli.tar.bz2 +OSCAL_CLI_BIN:=$(OSCAL_CLI_DIR)/bin/oscal-cli + +# Use oscal-cli from PATH if available, otherwise use local installation +OSCAL_CLI_COMMAND:=$(or $(shell command -v oscal-cli 2>/dev/null),$(OSCAL_CLI_BIN)) + +.PHONY: install-oscal-cli +install-oscal-cli: ## Install oscal-cli if not available in PATH +ifeq ($(shell command -v oscal-cli 2>/dev/null),) +install-oscal-cli: $(OSCAL_CLI_BIN) +endif + +$(OSCAL_CLI_BIN): + @echo "oscal-cli not found in PATH, downloading version $(OSCAL_CLI_VERSION)..." + @command -v curl >/dev/null 2>&1 || { echo "Error: curl is required but not installed."; exit 1; } + @command -v bzip2 >/dev/null 2>&1 || { echo "Error: bzip2 is required but not installed."; exit 1; } + @mkdir -p $(OSCAL_CLI_DIR) + curl -fL -o "$(OSCAL_CLI_ARCHIVE)" "$(OSCAL_CLI_DOWNLOAD_URL)" + @echo "Extracting oscal-cli..." + @tar -xjf "$(OSCAL_CLI_ARCHIVE)" -C $(OSCAL_CLI_DIR) + @rm "$(OSCAL_CLI_ARCHIVE)" + @echo "oscal-cli installed to $(OSCAL_CLI_DIR)" + @chmod +x $(OSCAL_CLI_BIN) -METASCHEMA_XSLT_COMMAND:=metaschema-xslt/bin/metaschema-xslt SRC_DIR:=../src/metaschema # Contains all OSCAL metaschema modules, including those without exported roots ALL_METASCHEMAS:=$(shell find $(SRC_DIR) -name '*_metaschema.xml') @@ -45,60 +72,16 @@ JSONSCHEMA_OUTPUTS:=$(patsubst $(SRC_DIR)/%_metaschema.xml,$(GENERATED_DIR)/%_sc $(GENERATED_DIR)/%_schema.json $(GENERATED_DIR)/%_schema.xsd: $(SRC_DIR)/%_metaschema.xml @mkdir -p $(GENERATED_DIR) - $(METASCHEMA_XSLT_COMMAND) schema-gen $(SRC_DIR)/$*_metaschema.xml $(GENERATED_DIR) $* - + $(OSCAL_CLI_COMMAND) metaschema generate-schema --as=json --overwrite $(SRC_DIR)/$*_metaschema.xml $(GENERATED_DIR)/$*_schema.json + $(OSCAL_CLI_COMMAND) metaschema generate-schema --as=xml --overwrite $(SRC_DIR)/$*_metaschema.xml $(GENERATED_DIR)/$*_schema.xsd .PHONY: schemas -schemas: $(XSD_OUTPUTS) $(JSONSCHEMA_OUTPUTS) ## Generate the schemas + +schemas: install-oscal-cli $(XSD_OUTPUTS) $(JSONSCHEMA_OUTPUTS) ## Generate the schemas .PHONY: clean-schemas clean-schemas: ## Remove generated schemas rm -fr $(GENERATED_DIR)/*_schema.* -######################## -# Converter Generation # -######################## - -XML2JSON_CONVERTERS:=$(patsubst $(SRC_DIR)/%_metaschema.xml,$(GENERATED_DIR)/%_xml-to-json-converter.xsl,$(METASCHEMAS)) -JSON2XML_CONVERTERS:=$(patsubst $(SRC_DIR)/%_metaschema.xml,$(GENERATED_DIR)/%_json-to-xml-converter.xsl,$(METASCHEMAS)) - -$(GENERATED_DIR)/%_xml-to-json-converter.xsl $(GENERATED_DIR)/%_json-to-xml-converter.xsl: $(SRC_DIR)/%_metaschema.xml - @mkdir -p $(GENERATED_DIR) - $(METASCHEMA_XSLT_COMMAND) converter-gen $(SRC_DIR)/$*_metaschema.xml $(GENERATED_DIR) $* - -.PHONY: converters -converters: $(XML2JSON_CONVERTERS) $(JSON2XML_CONVERTERS) ## Generate the converters - -.PHONY: clean-converters -clean-converters: ## Remove generated converters - rm -fr $(GENERATED_DIR)/*_xml-to-json-converter.xsl - rm -fr $(GENERATED_DIR)/*_json-to-xml-converter.xsl - -################################### -# Resolved Metaschemas Generation # -################################### - -POM_PATH:=./pom.xml -define EXEC_SAXON - mvn --quiet -f "$(POM_PATH)" exec:java \ - -Dexec.mainClass="net.sf.saxon.Transform" \ - -Dexec.args="$1" -endef - -RESOLVER_STYLESHEET:=./resolve-entities.xsl - -RESOLVED_METASCHEMA_SUFFIX:=RESOLVED -RESOLVED_METASCHEMAS:=$(patsubst $(SRC_DIR)/%_metaschema.xml,$(GENERATED_DIR)/%_metaschema_$(RESOLVED_METASCHEMA_SUFFIX).xml,$(ALL_METASCHEMAS)) - -$(GENERATED_DIR)/%_metaschema_$(RESOLVED_METASCHEMA_SUFFIX).xml: $(SRC_DIR)/%_metaschema.xml - @mkdir -p $(GENERATED_DIR) - $(call EXEC_SAXON,-s:$(SRC_DIR)/$*_metaschema.xml -xsl:$(RESOLVER_STYLESHEET) -o:$@ importHrefSuffix=$(RESOLVED_METASCHEMA_SUFFIX)) - -.PHONY: resolved-metaschemas -resolved-metaschemas: $(RESOLVED_METASCHEMAS) ## Generate the resolved metaschema modules - -.PHONY: clean-resolved-metaschemas -clean-resolved-metaschemas: ## Remove generated resolvd metaschema modules - rm -f $(RESOLVED_METASCHEMAS) ###################### # Archive Generation # @@ -110,18 +93,17 @@ TARBZ2_ARCHIVE:=$(GENERATED_DIR)/oscal-$(RELEASE).tar.bz2 ARCHIVE_TEMP_DIR:=$(GENERATED_DIR)/archive_temp .PHONY: archives -archives: $(ZIP_ARCHIVE) ## Archive converters and schemas +archives: $(ZIP_ARCHIVE) ## Archive schemas and metaschemas -$(ZIP_ARCHIVE) $(TARBZ2_ARCHIVE): converters schemas resolved-metaschemas +$(ZIP_ARCHIVE) $(TARBZ2_ARCHIVE): schemas @echo Generating archive - mkdir -p $(ARCHIVE_TEMP_DIR)/{{json,xml}/{convert,schema},metaschema} + @command -v zip >/dev/null 2>&1 || { echo "Error: zip is required but not installed."; exit 1; } + mkdir -p $(ARCHIVE_TEMP_DIR)/{{json,xml}/schema,metaschema} cp ../src/release/release-readme.txt "$(ARCHIVE_TEMP_DIR)/README.txt" cp $(XSD_OUTPUTS) "$(ARCHIVE_TEMP_DIR)/xml/schema" cp $(JSONSCHEMA_OUTPUTS) "$(ARCHIVE_TEMP_DIR)/json/schema" - cp $(XML2JSON_CONVERTERS) "$(ARCHIVE_TEMP_DIR)/xml/convert" - cp $(JSON2XML_CONVERTERS) "$(ARCHIVE_TEMP_DIR)/json/convert" - cp $(RESOLVED_METASCHEMAS) "$(ARCHIVE_TEMP_DIR)/metaschema" + cp $(ALL_METASCHEMAS) "$(ARCHIVE_TEMP_DIR)/metaschema" (cd "$(ARCHIVE_TEMP_DIR)" && zip -r $(abspath $(ZIP_ARCHIVE)) .) tar -jcvf "$(TARBZ2_ARCHIVE)" -C "$(ARCHIVE_TEMP_DIR)" . @@ -129,7 +111,7 @@ $(ZIP_ARCHIVE) $(TARBZ2_ARCHIVE): converters schemas resolved-metaschemas rm -fr $(ARCHIVE_TEMP_DIR) .PHONY: clean-archives -clean-archives: ## Clean generated archive of converters and schemas +clean-archives: ## Clean generated archives rm -fr $(ARCHIVE_TEMP_DIR) rm -fr $(ZIP_ARCHIVE) $(TARBZ2_ARCHIVE) @@ -167,7 +149,7 @@ clean-linkcheck: ## Remove linkcheck log ####################### .PHONY: validate -validate: validate-jsonschemas validate-xsds validate-composition ## Validate all generated content +validate: validate-jsonschemas validate-xsds validate-metaschemas ## Validate all generated content .PHONY: validate-jsonschemas validate-jsonschemas: node_modules $(JSONSCHEMA_OUTPUTS) ## Validate generated JSON Schemas @@ -177,21 +159,15 @@ validate-jsonschemas: node_modules $(JSONSCHEMA_OUTPUTS) ## Validate generated J .PHONY: validate-xsds validate-xsds: $(XSD_OUTPUTS) ## Validate generated XSD files @echo Validating generated XSDs + @command -v xmllint >/dev/null 2>&1 || { echo "Error: xmllint is required but not installed. Install libxml2-utils."; exit 1; } xmllint --noout $(XSD_OUTPUTS) -VALIDATE_COMPOSITION_TARGETS:=$(patsubst $(SRC_DIR)/oscal_%_metaschema.xml,validate-composition-%,$(METASCHEMAS)) - -.PHONY: validate-composition -validate-composition: $(VALIDATE_COMPOSITION_TARGETS) ## Validate source metaschemas - -validate-composition-%: - @echo Performing composition validation of the $* model via schematron - $(METASCHEMA_XSLT_COMMAND) composition-validate $(SRC_DIR)/oscal_$*_metaschema.xml - -.IGNORE: test-profile-resolution # TODO: fix up the profile resolution tests -.PHONY: test-profile-resolution -test-profile-resolution: ## Unit test the profile resolver - $(MAKE) -C ../src/utils/resolver-pipeline test +.PHONY: validate-metaschemas +validate-metaschemas: install-oscal-cli ## Validate source metaschemas + @for metaschema in $(ALL_METASCHEMAS); do \ + echo "Validating $$metaschema"; \ + $(OSCAL_CLI_COMMAND) metaschema validate "$$metaschema" || exit 1; \ + done ################### # Utility Targets # @@ -200,7 +176,7 @@ test-profile-resolution: ## Unit test the profile resolver # These targets may be used by consumers of the OSCAL repository # All artifacts typically included in a release -RELEASE_ARTIFACTS:=$(XSD_OUTPUTS) $(JSONSCHEMA_OUTPUTS) $(XML2JSON_CONVERTERS) $(JSON2XML_CONVERTERS) $(RESOLVED_METASCHEMAS) $(ZIP_ARCHIVE) $(TARBZ2_ARCHIVE) +RELEASE_ARTIFACTS:=$(XSD_OUTPUTS) $(JSONSCHEMA_OUTPUTS) $(ZIP_ARCHIVE) $(TARBZ2_ARCHIVE) # This target is used by OSCAL-Reference to generate meta-redirects for release assets .PHONY: list-release-artifacts diff --git a/build/README.md b/build/README.md index cfcf561cd6..3d8a7cb0a8 100644 --- a/build/README.md +++ b/build/README.md @@ -1,13 +1,13 @@ # OSCAL Build Tools -This subdirectory contains infrastructure used to create OSCAL-related artifacts (e.g., schemas, converters) and perform status checks. +This subdirectory contains infrastructure used to create OSCAL-related artifacts (e.g., schemas) and perform status checks. Below are instructions for using these tools. ## Prerequisites The build tools in this directory require a Unix environment with the following software: -- [Maven](https://maven.apache.org/): Required to generate artifacts +- [oscal-cli](https://github.com/metaschema-framework/oscal-cli): Used to generate schemas and validate metaschemas. If `oscal-cli` is not found in your `PATH`, the build system will automatically download and install it locally. - [NodeJS](https://nodejs.org/en) (ensure the version matches [`.nvmrc`](./.nvmrc)): Required to perform link checking - [`libxml`](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home): Provides `xmllint` which is required to validate generated XML artifacts @@ -29,13 +29,12 @@ Note that running jobs concurrently will make the output harder to follow and de As of `v1.1.0`, artifacts are no longer tracked in the OSCAL git repository ([discussion link](https://github.com/usnistgov/OSCAL/discussions/1852)). Instead artifacts are [generated as part of a release](../.github/workflows/release.yml). -Developers can generate schemas locally using the `make artifacts` command. +Developers can generate schemas locally using the `make artifacts` command. Schema generation uses [oscal-cli](https://github.com/metaschema-framework/oscal-cli), which will be auto-downloaded if not already available in your `PATH`. Developers can also generate individual artifacts using the following commands: -* `make schemas`: Generates the JSON Schemas and XSDs off of the source Metaschemas; -* `make converters`: Generates the XSLT stylesheets for JSON<->XML conversion off of the source Metaschemas; -* `make resolved-metaschemas`: Resolves external entities (XXE) present in the source OSCAL Metaschema modules for use with tools that do not support XXEs. +* `make schemas`: Generates the JSON Schemas and XSDs from the source Metaschemas using oscal-cli; +* `make validate-metaschemas`: Validates all source Metaschema modules using oscal-cli. ### Checks @@ -46,6 +45,7 @@ The checks can also be run individually: * `make linkcheck`: Checks each markdown file in the repository for bad links; * `make validate-jsonschemas`: Validates that the JSON schemas generated by `make schemas` are schema valid against the JSON Schema specification; * `make validate-xsds`: Validates that the XSD files generated by `make schemas` are schema valid against the XSD specification; +* `make validate-metaschemas`: Validates all source Metaschema modules using oscal-cli; * `make test-profile-resolution`: Runs the test suite in [`/src/utils/resolver-pipeline`](../src/utils/resolver-pipeline/). ### Archive Generation @@ -92,91 +92,44 @@ xmllint --noout --schema "oscal_catalog_schema.xsd" "catalog.xml" The [online documentation](http://xmlsoft.org/xmllint.html) for *xmllint* provides more information on the command-line arguments. -### Converters +### Content Conversion -The OSCAL project provides Extensible Stylesheet Language Transformation (XSLT) templates based on [XSLT 3.0](https://www.w3.org/TR/xslt-30/) and [XPath 3.1](https://www.w3.org/TR/xpath-31/) for all [OSCAL models](https://pages.nist.gov/OSCAL/documentation/schema/). +OSCAL content can be converted between XML, JSON, and YAML formats using [oscal-cli](https://github.com/metaschema-framework/oscal-cli). -**IMPORTANT** : XSLT 3.0 and XPath 3.1 are only required when using the NIST provided tools for converting OSCAL content between JSON and XML. Any version of XSLT or XPath may be used when transforming or querying OSCAL files for other reasons. These newer versions of XSLT and XPath offer more robust capabilities, that are needed to support the OSCAL converters. +#### Converting OSCAL Content with oscal-cli -After running `make converters`, converter stylesheets will be created in the `generated/` directory, following the general pattern `oscal_[MODEL_NAME]_json-to-xml-converter.xsl` and `oscal_[MODEL_NAME]_xml-to-json-converter.xsl`. +The `oscal-cli` tool provides a `convert` command that supports conversion between XML, JSON, and YAML formats for all OSCAL models. The tool automatically detects the source format and the OSCAL model type. -Pre-built converters are also distributed as part of a [release](https://github.com/usnistgov/OSCAL/releases). - -#### Converting OSCAL XML Content to JSON - -The OSCAL project uses [Saxon-HE (Saxon Home Edition)](http://saxon.sourceforge.net/) to evaluate the XSLT templates supporting conversion of OSCAL XML and JSON [content](https://github.com/usnistgov/oscal-content) provided in this repository. *Saxon-HE* is an open source implementation of XSLT 3.0, XPath 2.0 and 3.1, and XQuery 3.1 supporting Java and .NET programming environments. These versions of *Saxon-HE* can be [downloaded directly](http://saxon.sourceforge.net/#F9.9HE) or the Java version can be [downloaded](https://search.maven.org/artifact/net.sf.saxon/Saxon-HE) using Apache Maven. Saxonica also offers Saxon PE and EE versions, which are commercial products with technical support and redistribution rights. - -The OSCAL project uses *Saxon-HE* with Java version 8 or greater. - -The following example uses **Saxon HE** to convert an OSCAL catalog XML file to JSON using one of the NIST-provided JSON to XML XSLT converters. This example assumes that Java 8+ has been installed and the Saxon-HE jar files have already unzipped. +The general syntax is: ``` -java -jar "saxon10he.jar" -xsl:"oscal_catalog_xml-to-json-converter.xsl" -s:"oscal-catalog.xml" -o:"oscal-catalog.json" json-indent=yes +oscal-cli convert --to= [] ``` -> *Note*: at time of writing, Saxon 9 users are being encouraged to upgrade systems to use Saxon 10, and the stylesheets provided should function equally well or better with the later software. Please feel free to use the latest Saxon or indeed any conformant XSLT 3.0 processor. -> -> Operators of XSLT-based platforms should by all means test these processes with any XSLT 3.0 conformant processor, and report problems to us via Github Issues. - -Paths\names of these files need to be provided based on the location of the files on your computer: - -* The Saxon JAR file is named ```saxon10he.jar```. -* The catalog converter is specified as ```-xsl:"oscal_catalog_xml-to-json-converter.xsl"``` -* The source catalog XML file is specified as ```-s:"oscal-catalog.xml"``` -* The destination catalog JSON file is specified as ```-o:"oscal-catalog.json"```. - -The [online documentation](http://www.saxonica.com) for *Saxon* provides more information on the command line arguments. - -##### Alternate invocations - -The configuration just provided will convert a JSON file given as a file reference, into OSCAL XML. There are also different configurations available for debugging: - -* `-it:from-xml` (indicating initial template) - provides the default XSLT entry point explicitly. -* `-file:mycatalog.xml` used with explicit `-it:from-xml` will look for the XML at the location given by the parameter, instead of on the source port (given by `-s`). This configuration parallels the JSON-to-XML converter. -* `produce=supermodel` as a runtime parameter will emit not OSCAL XML, but the intermediate format produced by the converter (a so-called 'OSCAL supermodel' derived from its metaschema): useful for debugging or as a pivot to other serializations. -* `produce=xpath-json` will produce the results in an XML format defined by the XPath function `json-to-xml()`, which when consumed by the complementary function `xml-to-json()` can deterministically provide syntactically correct JSON. This XML format is used internally to provide the JSON data description, to be cast into JSON as a (terminal) serialization step. Expressing the transformation results in this format directly can provide insight for debugging, especially in failure conditions (when the syntax cannot be written). See https://www.w3.org/TR/xpath-functions-31/#func-json-to-xml for more details on this format. +Where `` is one of: `XML`, `JSON`, or `YAML`. -#### Converting OSCAL JSON Content to XML +#### Examples -The OSCAL project uses [Saxon-HE (Saxon Home Edition)](http://saxon.sourceforge.net/) to evaluate the XSLT templates supporting conversion of OSCAL XML and JSON [content](https://github.com/usnistgov/oscal-content) provided in this repository. *Saxon-HE* is an open source implementation of XSLT 3.0, XPath 2.0 and 3.1, and XQuery 3.1 supporting Java and .NET programming environments. These versions of *Saxon-HE* can be [downloaded directly](http://saxon.sourceforge.net/#F9.9HE) or the Java version can be [downloaded](https://search.maven.org/artifact/net.sf.saxon/Saxon-HE) using Apache Maven. Saxonica also offers Saxon PE and EE versions, which are commercial products with technical support and redistribution rights. - -The OSCAL project uses *Saxon-HE* with Java version 8 or greater. - -The following example uses **Saxon HE** to convert an OSCAL catalog JSON file to XML using one of the NIST-provided JSON to XML XSLT converters. This example assumes that has been installed and the Saxon-HE jar files have already unzipped. +Convert an OSCAL catalog from XML to JSON: ``` -java -jar "saxon10he.jar" -xsl:"oscal_catalog_json-to-xml-converter.xsl" -o:"oscal-catalog.xml" -it:from-json file="oscal-catalog.json" +oscal-cli convert --to=JSON oscal-catalog.xml oscal-catalog.json ``` -> *Note*: at time of writing, Saxon 9 users are being encouraged to upgrade systems to use Saxon 10, and the stylesheets provided should function equally well or better with the later software. Please feel free to use the latest Saxon or indeed any conformant XSLT 3.0 processor. -> -> Operators of XSLT-based platforms should by all means test these processes with any XSLT 3.0 conformant processor, and report problems to us via Github Issues. - -`-it` indicates the initial template (XSLT entry point) should be `from-json`. (As documented in the source code, other entry points are offered for diagnostics or integration.) - -Paths/names given to other settings are offered as relative or absolute system paths or URIs: - -* The Saxon JAR file is named ```saxon9he.jar``` (system path). -* The catalog converter is specified as ```-xsl:"oscal_catalog_json-to-xml-converter.xsl"``` (relative or absolute URI) -* The source catalog JSON file is specified as ```file="oscal-catalog.json"``` (URI) -* The destination catalog XML file is specified as ```-o:"oscal-catalog.xml"``` (URI) +Convert an OSCAL SSP from JSON to XML: -The [online documentation](http://www.saxonica.com) for *Saxon* provides more information on the command line arguments. - -##### Alternate invocations - -The configuration just provided will convert a JSON file given as a file reference, into OSCAL XML. However it may sometimes be convenient (for example when invoking programmatically) to pass the JSON into the converter as a literal. +``` +oscal-cli convert --to=XML ssp.json ssp.xml +``` -Use the `json` runtime parameter to do this. On the command line this might be: +To overwrite an existing destination file, add the `--overwrite` flag: ``` -java -jar "saxon10he.jar" -xsl:"oscal_catalog_json-to-xml-converter.xsl" -o:"oscal-catalog.xml" -it:from-json json="{ "catalog": {} }" +oscal-cli convert --to=JSON --overwrite oscal-catalog.xml oscal-catalog.json ``` -(With allowances made for quote marks etc.) +If no destination file is specified, the converted output is written to stdout. -There are also different configurations available for debugging: +You can also use model-specific subcommands (e.g., `oscal-cli catalog convert`, `oscal-cli ssp convert`) for the same functionality. -* `-it` (initial template) `from-xdm-json-xml` - assume the source is not given as a URI reference to a file, but as XML conformant to the model returned by the XPath function 'json-to-xml()'. In this case, the `file` parameter must point to this XML file not a JSON file. -* Alternatively, `-s:file.xml` (with or instead of `-it`) will operate the same way, except finding the XML at `file.xml`. -* `produce=supermodel` as a runtime parameter will emit not OSCAL XML, but the intermediate format produced by the converter (a so-called 'OSCAL supermodel' derived from its metaschema): useful for debugging or as a pivot to other serializations. +See the [oscal-cli documentation](https://github.com/metaschema-framework/oscal-cli) for more information on available commands and options. diff --git a/build/metaschema-xslt b/build/metaschema-xslt deleted file mode 160000 index 8e5b2ca522..0000000000 --- a/build/metaschema-xslt +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 8e5b2ca5226e49338c49bede9bdd28c9a0737fbe diff --git a/build/pom.xml b/build/pom.xml deleted file mode 100644 index c1daf5507d..0000000000 --- a/build/pom.xml +++ /dev/null @@ -1,65 +0,0 @@ - - 4.0.0 - - gov.nist.secauto.oscal.tools.core - oscal-support - 1.0.0 - - - UTF-8 - - - pom - - - - - maven.restlet.org - maven.restlet.org - https://maven.restlet.talend.com - - - - - - net.sf.saxon - Saxon-HE - 11.5 - - - com.xmlcalabash - xmlcalabash - 3.0.31 - - - - - - - org.apache.maven.plugins - maven-dependency-plugin - 3.9.0 - - - copy-dependencies - package - - copy-dependencies - - - - - - - - diff --git a/build/resolve-entities.xsl b/build/resolve-entities.xsl deleted file mode 100644 index 9f8971f88c..0000000000 --- a/build/resolve-entities.xsl +++ /dev/null @@ -1,60 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/build/xslt-runner.sh b/build/xslt-runner.sh deleted file mode 100755 index 1763187393..0000000000 --- a/build/xslt-runner.sh +++ /dev/null @@ -1,38 +0,0 @@ -#!/usr/bin/env bash -# XSLT Transform Runner Utility - -set -Eeuo pipefail - -usage() { - cat <&2 - exit 1 -fi - -[[ -z "${1-}" ]] && { echo "Error: SOURCE not specified"; usage; exit 1; } -ENTRY_STYLESHEET=$1 - -[[ -z "${2-}" ]] && { echo "Error: SOURCE not specified"; usage; exit 1; } -SOURCE=$2 -[[ -z "${3-}" ]] && { echo "Error: OUTPUT not specified"; usage; exit 1; } -OUTPUT=$3 - -ADDITIONAL_ARGS=$(shift 3; echo $@) - -SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd)" -POM_FILE="${SCRIPT_DIR}/pom.xml" - -mvn \ - -f $POM_FILE \ - exec:java \ - -Dexec.mainClass="net.sf.saxon.Transform" \ - -Dexec.args="-t -xsl:$ENTRY_STYLESHEET -s:$SOURCE -o:$OUTPUT $ADDITIONAL_ARGS" diff --git a/build/xspec b/build/xspec deleted file mode 160000 index 8797c846c3..0000000000 --- a/build/xspec +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 8797c846c3249f31efe0a047aae52856705250d9 diff --git a/src/release/release-readme.txt b/src/release/release-readme.txt index 10439713fb..8b3f5dd2be 100644 --- a/src/release/release-readme.txt +++ b/src/release/release-readme.txt @@ -7,17 +7,18 @@ Documentation for the OSCAL models can be found at: https://pages.nist.gov/OSCAL # Release Contents -This release provides 2 types of resources, each located in a different subdirectory: +This release provides the following resources, each located in a different subdirectory: -- `xml/` and `json/`: Provides the XML and JSON schemas and content converters that are needed to support the OSCAL model. Instructions for using these artifacts can be found at https://github.com/usnistgov/OSCAL/blob/develop/build/README.md#artifact-usage -- `metaschema/`: Provides the source OSCAL Metaschema modules with all external entities (XXE) resolved for tools that do not support XXEs. +- `xml/schema/`: XML Schema Definition (XSD) files for validating OSCAL XML content. +- `json/schema/`: JSON Schema files for validating OSCAL JSON content. +- `metaschema/`: Source OSCAL Metaschema definition modules with all external entities (XXE) resolved for tools that do not support XXEs. + +Instructions for using these artifacts, including schema validation and content conversion with oscal-cli, can be found at https://github.com/usnistgov/OSCAL/blob/develop/build/README.md#artifact-usage These directories provide stable, released versions of the resources provided on the OSCAL GitHub repository: https://github.com/usnistgov/OSCAL. Please note that OSCAL content examples, which were once included in these archives are now located at: https://github.com/usnistgov/oscal-content. -If you have existing content targeting the previous `oscal-version` from a prior release, you can use the content upgrade transforms to upgrade them to this release as documented in this directory's README: https://github.com/usnistgov/OSCAL/tree/main/src/release/content-upgrade/. - # The OSCAL Roadmap OSCAL is being developed through a series of milestone releases, which are focused around stabilizing the OSCAL model layers in a progression. While the project is being developed iteratively, the OSCAL team is working to reduce the impact of changes between each milestone release, to provide for early adoption of OSCAL content and the development of tools supporting the lower-layer models.