### Example Requirement Tagging in SpecML

Source: https://github.com/usnistgov/oscal/blob/main/src/specifications/profile-resolution/readme.md

Demonstrates how requirements and examples are tagged within SpecML documents. The `@href` attribute links to example files, and a `PENDING` prefix can deactivate a test.

```xml
<eg href="requirement-tests/req-chained-deepA.xml">PENDING chained profiles</eg>
```

--------------------------------

### Example Script Output for Docker Image Tagging

Source: https://github.com/usnistgov/oscal/wiki/Software-we-use:-Docker

This is an example of the output you might see from the build script, indicating the image tag and instructions for pushing it.

```bash
# Script output from build-oscal-env-dockerfile.sh
Built and tagged csd773/oscal-common-env:fixed-a-thing, to push run:
    docker push csd773/oscal-common-env:fixed-a-thing
```

--------------------------------

### Example GitHub Actions Repository

Source: https://github.com/usnistgov/oscal/wiki/NIST-Team:-Lunch-and-Learn-Archive

This repository contains example code for learning GitHub Actions. It is used for testing and demonstration purposes.

```yaml
# This is a placeholder for a GitHub Actions workflow file.
# The actual content would be in the linked repository.
name: Example Workflow

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Run a one-line script
      run: echo Hello, world!
```

--------------------------------

### Handmade XSpec Example

Source: https://github.com/usnistgov/oscal/blob/main/src/specifications/profile-resolution/readme.md

An example of a handmade XSpec file that is not automatically generated. This specific file is named `profile-resolution-queryset.xspec`.

```xml
profile-resolution-queryset.xspec
```

--------------------------------

### Example Metaschema Modules, XML Schemas, and Instances

Source: https://github.com/usnistgov/oscal/wiki/NIST-Team:-Lunch-and-Learn-Archive

This Gist contains example Metaschema modules, XML schemas, and instances used in the session on schema validation. It demonstrates constraint processing.

```xml
<!-- This is a placeholder for an XML Schema example. -->
<!-- The actual content would be in the linked Gist. -->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="example" type="xs:string"/>
</xs:schema>
```

```xml
<!-- This is a placeholder for an XML instance example. -->
<!-- The actual content would be in the linked Gist. -->
<example>Sample Data</example>
```

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Example JSON Schema",
  "type": "string"
}
```

--------------------------------

### Example: OSCAL Catalog Schema JSON File

Source: https://github.com/usnistgov/oscal/blob/main/src/file-naming-conventions.md

This is an example of an OSCAL catalog schema file named according to the convention, specifying the model, revision, and file extension.

```text
oscal_catalog_schema_1.0-M1.json
```

--------------------------------

### Initialize Git Submodules

Source: https://github.com/usnistgov/oscal/blob/main/CONTRIBUTING.md

Execute this command after cloning if submodules were not automatically initialized, or for first-time setup.

```bash
git submodule update --init
```

--------------------------------

### Example: OSCAL Profile Schema XSD File

Source: https://github.com/usnistgov/oscal/blob/main/src/file-naming-conventions.md

This is an example of an OSCAL profile schema file named without a specific revision, indicating it's the latest version.

```text
oscal_profile_schema.xsd
```

--------------------------------

### Example OSCAL Catalog File Name

Source: https://github.com/usnistgov/oscal/blob/main/src/file-naming-conventions.md

An example of a correctly named OSCAL catalog file adhering to the specified convention.

```text
NIST_SP-800-53_rev4_catalog.xml
```

--------------------------------

### Clone OSCAL Repository with Submodules

Source: https://github.com/usnistgov/oscal/blob/main/README.md

Use this command to clone the OSCAL repository and initialize all its submodules. Ensure Git is installed and configured on your system.

```bash
git clone --recurse-submodules https://github.com/usnistgov/OSCAL.git
```

--------------------------------

### Example: OSCAL Catalog JSON to XML Converter XSLT

Source: https://github.com/usnistgov/oscal/blob/main/src/file-naming-conventions.md

This example shows an XSLT file named for converting OSCAL catalog data from JSON to XML format.

```text
oscal_catalog_json-to-xml-converter.xsl
```

--------------------------------

### Example OSCAL Profile File Name with Specifier

Source: https://github.com/usnistgov/oscal/blob/main/src/file-naming-conventions.md

An example of an OSCAL profile file name that includes a specifier to denote a specific baseline.

```text
NIST_SP-800-53_rev4_LOW-baseline_profile.json
```

--------------------------------

### XSLT for Generating File-Based XSpec

Source: https://github.com/usnistgov/oscal/blob/main/src/specifications/profile-resolution/readme.md

This XSpec is generated by applying the XSLT `lib/build-examples-xspec.xsl` to the SpecML source document. It groups tests by file, which may be more efficient to execute due to the many-to-many relationship between requirements and examples.

```xml
This XSpec is generated by applying the XSLT `lib/build-examples-xspec.xsl` to the same SpecML source document.
```

--------------------------------

### Upgrade OSCAL Content via Command Line

Source: https://github.com/usnistgov/oscal/blob/main/src/release/content-upgrade/README.md

Use this command to upgrade OSCAL content from one version to another using Saxon HE. Ensure Java Runtime Environment and Saxon HE are installed.

```sh
java -cp Saxon-HE-10.6.jar net.sf.saxon.Transform -xsl:oscal-rc2-v1-0-0-update.xsl -s:catalog_v1.0.0-rc2.xml -o:catalog_v1.0.0.xml
```

--------------------------------

### Run Interactive Session in OSCAL Docker Container

Source: https://github.com/usnistgov/oscal/wiki/Software-we-use:-Docker

To start an interactive terminal session within the OSCAL Docker container, use the '-it' flags and omit the command. The current directory is mounted to '/oscal'.

```bash
docker run -it \
    -v $(pwd):/oscal \
    csd773/oscal-common-env:fixed-a-thing
```

--------------------------------

### Invoke Java Dependency from pom.xml

Source: https://github.com/usnistgov/oscal/wiki/Code:-Java‐based-Tooling

This bash script uses Maven to execute a Java class specified in a POM file. Ensure Maven is installed and in your PATH. The script resolves the OSCAL root directory and constructs the Maven command to run the specified main class with provided arguments.

```bash
#!/usr/bin/env bash

# Fail early if an error occurs
set -Eeuo pipefail

if ! [ -x "$(command -v mvn)" ]; then
  echo 'Error: Maven (mvn) is not in the PATH, is it installed?' >&2
  exit 1
fi

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd)"
OSCAL_DIR="${SCRIPT_DIR}/../../../.." # Edit this to resolve to the OSCAL root from the script's directory
POM_FILE="${OSCAL_DIR}/build/pom.xml"
# Grab any additional files relative to the root OSCAL directory (like stylesheets)

MAIN_CLASS="net.sf.saxon.Transform" #edit this to target your application's main class. below are a few examples:
# XML Calabash: "com.xmlcalabash.drivers.Main"
# Saxon: "net.sf.saxon.Transform"

# Perform any argument processing here, such as preselecting stylesheets in Saxon, etc.
# Note here "${*// /\ }" is a shell expansion that escapes spaces within arguments.
# For more information, see https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html
ARGS=${*// /\ }

mvn \
    -f "$POM_FILE" \
    exec:java \
    -Dexec.mainClass="$MAIN_CLASS" \
    -Dexec.args="$ARGS"

```

--------------------------------

### Run Make Help

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Run `make help` to see a summary of available build targets.

```bash
make help
```

--------------------------------

### XProc 1.0 Tutorial Code

Source: https://github.com/usnistgov/oscal/wiki/NIST-Team:-Lunch-and-Learn-Archive

This GitHub repository contains Wendell's tutorial code for XProc 1.0, used for orchestrating XSLT and XML-based processing.

```xml
<!-- This is a placeholder for an XProc 1.0 pipeline example. -->
<!-- The actual content would be in the linked repository. -->
<p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
            version="1.0">
  <p:output port="result"/>
  <p:identity/>
</p:pipeline>
```

--------------------------------

### Checkout Develop Branch

Source: https://github.com/usnistgov/oscal/wiki/OSCAL-Patch-(Hot-Fix)-Release-Checklist

Switch to the 'develop' branch to prepare for building artifacts for the upcoming release.

```sh
git checkout develop
```

--------------------------------

### Log in to Docker CLI

Source: https://github.com/usnistgov/oscal/wiki/Software-we-use:-Docker

Run this command to log in to the Docker registry. Follow the on-screen prompts for authentication.

```bash
docker login
```

--------------------------------

### Example OSCAL Profile File Name without Specifier

Source: https://github.com/usnistgov/oscal/blob/main/src/file-naming-conventions.md

An example of an OSCAL profile file name where the source name is sufficient to identify the profile, thus omitting a specifier.

```text
FedRAMP_MODERATE-baseline_profile.xml
```

--------------------------------

### Generate All Artifacts and Run Checks

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Run `make all` to generate all artifacts and perform all status checks.

```bash
make all
```

--------------------------------

### Run Profile Resolution Tests

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Runs the test suite in [`/src/utils/resolver-pipeline`](../src/utils/resolver-pipeline/).

```bash
make test-profile-resolution
```

--------------------------------

### Run All Checks

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Developers can run checks using the `make checks` command.

```bash
make checks
```

--------------------------------

### Validate OSCAL XML Content with xmllint

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Use xmllint to validate OSCAL XML files against their corresponding XSD schemas. Ensure xmllint is installed.

```bash
xmllint --noout --schema "oscal_catalog_schema.xsd" "catalog.xml"
```

--------------------------------

### Validate OSCAL JSON Content with ajv-cli

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Use ajv-cli to validate OSCAL JSON files against their corresponding schemas. Ensure Node.js is installed and ajv-cli is set up.

```bash
ajv validate -s "oscal_catalog_schema.json" -d "catalog.json" --extend-refs=true --verbose
```

--------------------------------

### Generate All Artifacts

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Developers can generate schemas locally using the `make artifacts` command.

```bash
make artifacts
```

--------------------------------

### Generate Archives

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

`make archives` generates `.zip` and `.tar.bz2` archives with the generated artifacts.

```bash
make archives
```

--------------------------------

### Push Docker Image to Registry

Source: https://github.com/usnistgov/oscal/wiki/Software-we-use:-Docker

After building a custom Docker image locally, use this command to push it to the registry. Replace '$TAG' with the actual tag of your built image.

```bash
docker push csd773/oscal-common-env:$TAG # where $TAG is the tag of your built image
```

--------------------------------

### Convert OSCAL JSON Catalog to XML

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Use this command to convert a JSON catalog file to XML using the NIST-provided XSLT converter with Saxon-HE. Ensure Saxon-HE is installed and its JAR files are unzipped.

```bash
java -jar "saxon10he.jar" -xsl:"oscal_catalog_json-to-xml-converter.xsl" -o:"oscal-catalog.xml" -it:from-json file="oscal-catalog.json"
```

--------------------------------

### Create a Release Branch

Source: https://github.com/usnistgov/oscal/wiki/Contributing-to-OSCAL--development-and-maintenance

Use this command to create a new release branch from the 'develop' branch. This prepares code for an upcoming release.

```git
git checkout -b release-1.2 develop
# TODO: need a method to bump version numbers in metaschemas and content
git commit -a -m "Bumped version number to 1.2"
git push --set-upstream upstream release-1.2
```

--------------------------------

### Run Link Check

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Checks each markdown file in the repository for bad links.

```bash
make linkcheck
```

--------------------------------

### Validate OSCAL JSON with ajv-cli

Source: https://github.com/usnistgov/oscal/blob/main/README_validations.md

Validate an OSCAL JSON file using `ajv-cli`. Ensure `ajv-formats` is installed for runtime compatibility. The `-s` flag specifies the schema, `-d` specifies the data file, and `-c` specifies the compiled schema.

```bash
# Install the ajv-formats library in NodeJS runtime to avoid runtime errors.
npm install -g ajv-formats ajv-cli
ajv-cli validate -s oscal-schema.json -d oscal.json -c ajv-formats
oscal.json valid
```

--------------------------------

### Clean and Build Release Artifacts

Source: https://github.com/usnistgov/oscal/wiki/OSCAL-Patch-(Hot-Fix)-Release-Checklist

Clean previous artifacts and generate all necessary artifacts for a specific release to a temporary directory. This is used for both the latest release and the upcoming release builds.

```sh
cd build # Make your way to the OSCAL build/ dir
make clean GENERATED_DIR=generated_LATEST_release # Ensure all old release artifacts have been deleted
make all GENERATED_DIR=generated_LATEST_release   # Generate all artifacts to an ignored directory
```

```sh
cd build # Make your way to the OSCAL build/ dir
make clean GENERATED_DIR=generated_NEW_release # Ensure any release artifacts have been deleted
make all GENERATED_DIR=generated_NEW_release   # Generate all artifacts to an ignored directory
```

--------------------------------

### Convert OSCAL XML to JSON using Saxon-HE

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Use this command to convert an OSCAL catalog XML file to JSON. Ensure Java 8+ is installed and Saxon-HE JAR files are unzipped. Provide the correct paths for the Saxon JAR, XSLT converter, source XML, and destination JSON files.

```bash
java -jar "saxon10he.jar" -xsl:"oscal_catalog_xml-to-json-converter.xsl" -s:"oscal-catalog.xml" -o:"oscal-catalog.json" json-indent=yes
```

--------------------------------

### Generate Custom Release Archives

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Archives will have the suffix `SNAPSHOT` by default, but this can be overridden using the `RELEASE` variable.

```bash
make archive RELEASE=my_release
```

--------------------------------

### Checkout Current Release Branch

Source: https://github.com/usnistgov/oscal/wiki/OSCAL-Patch-(Hot-Fix)-Release-Checklist

Use this command to check out the specific release branch for quality checks. This branch should be created from the latest release branch.

```sh
git checkout release-X.Y.
```

--------------------------------

### Create and Push New PR Branch using Git

Source: https://github.com/usnistgov/oscal/wiki/OSCAL-Tips-and-Tricks

Use this command sequence to create a new branch for a pull request targeting the 'develop' branch. Ensure you have cloned the repository and are in the project directory. The `git reset --hard origin/develop` command is critical for ensuring your local 'develop' branch is up-to-date and will discard any uncommitted local changes.

```sh
$ git clone git@github.com:usnistgov/OSCAL.git
$ pushd OSCAL
$ git remote -v # Ensure below origin has usnistgov in the URL, if not use the correct remote alias if not origin
origin  git@github.com:usnistgov/OSCAL.git (fetch)
origin  git@github.com:usnistgov/OSCAL.git (push)
$ git checkout --track origin/develop # first time
$ # or if you see an error that branch develop already exists
$ git checkout develop # after first time
$ git fetch --all # ensure if you have done the above days or weeks again
$ git reset --hard origin/develop # IMPORTANT: you will delete uncommitted work on your local develop, but you should not use this or main anyway
$ git checkout -b name-for-new-pr-branch-targeting-develop
$ git push origin HEAD # or the appropriate remote alias
```

--------------------------------

### Create a Feature Branch

Source: https://github.com/usnistgov/oscal/wiki/Contributing-to-OSCAL--development-and-maintenance

Use this command to create a new feature branch from 'develop'. Replace 'feature-NAME' with a descriptive label.

```git
git checkout -b feature-NAME develop
git push --set-upstream upstream feature-NAME
```

--------------------------------

### Build OSCAL Docker Image Locally

Source: https://github.com/usnistgov/oscal/wiki/Software-we-use:-Docker

Execute this script from the root of the OSCAL project to build the Docker image locally. The script will output the tag of the built image.

```bash
./build/build-oscal-env-dockerfile.sh
```

--------------------------------

### Generate Schemas

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Generates the JSON Schemas and XSDs off of the source Metaschemas.

```bash
make schemas
```

--------------------------------

### Local PR Testing Workflow

Source: https://github.com/usnistgov/oscal/wiki/Contributing-to-Pull-Request-Reviews

Steps to locally test changes proposed in a Pull Request. This involves cloning the repository, checking out the target branch, creating a new review branch, merging the PR changes, and then building and validating the artifacts.

```bash
clone locally the repo,
checkout the branch the PR is submitted against. This is the `develop` branch in the majority of cases.
create locally a new branch from the develop branch (e.g. `pr-xxx-review`). 
pull the proposed changes locally and merge them 
build and validate the artifacts (check for error)
review the results and build confidence the proposed PR changes are adequate.
```

--------------------------------

### Create Git Branch

Source: https://github.com/usnistgov/oscal/blob/main/CONTRIBUTING.md

Use this command to create a new branch for your development work. Replace 'working' with your desired branch name.

```git
git branch working
```

--------------------------------

### Sync Fork's Develop Branch with Upstream

Source: https://github.com/usnistgov/oscal/wiki/OSCAL-Tips-and-Tricks

Use these commands to reset your local fork's 'develop' branch to match the upstream 'develop' branch. Ensure your local 'origin' points to your fork and 'upstream' points to the usnistgov repository. This process will overwrite your local 'develop' branch.

```sh
git remote -v # If you results match below, you can skip the next few commands and skip to git fetch
origin      git@github.com:yourusername/OSCAL.git (fetch)
origin      git@github.com:yourusername/OSCAL.git (push)
upstream git@github.com:usnistgov/OSCAL.git (fetch)
upstream git@github.com:usnistgov/OSCAL.git (push)
git remote remove origin
git remote remove upstream # It may throw an error because it doesn't exist, this is to be safe.
git remote add upstream git@github.com:usnistgov/OSCAL.git
git remote add origin git@github.com:yourusername/OSCAL.git
git fetch --all # This is important or the next commands will reflect older "current" commits on the remotes, correct or incorrect.
git checkout --track origin/develop # first time
# Did you see the following error?
# 'fatal: A branch named 'develop' already exists.'
# If yes, you will do the command below after the first time.
git checkout develop # after first time
git reset --hard upstream/develop
git push origin develop -f
```

--------------------------------

### Generate Converters

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

Generates the XSLT stylesheets for JSON<->XML conversion off of the source Metaschemas.

```bash
make converters
```

--------------------------------

### Release a Release Branch to Main

Source: https://github.com/usnistgov/oscal/wiki/Contributing-to-OSCAL--development-and-maintenance

Commands to merge a completed release branch into 'main' and tag the release. This signifies a production-ready release.

```git
git checkout main
git merge --no-ff release-1.2
git tag -a 1.2.0
git push --follow-tags
```

--------------------------------

### Update Git Submodules

Source: https://github.com/usnistgov/oscal/wiki/Software-we-use:-Docker

Ensure your local project's submodules are up-to-date before building the Docker image. This command initializes and updates them recursively.

```bash
git submodule update --init --recursive
```

--------------------------------

### Enable xsi:schemaLocation in OSCAL Upgrade

Source: https://github.com/usnistgov/oscal/blob/main/src/release/content-upgrade/README.md

Use this command to apply the transform and explicitly add the `xsi:schemaLocation` attribute to the OSCAL document root. Ensure correct quoting for the parameter value.

```bash
java -cp Saxon-HE-10.6.jar net.sf.saxon.Transform -xsl:oscal-rc2-v1-0-0-update.xsl -s:catalog_v1.0.0-rc2.xml -o:catalog_v1.0.0.xml schema-location="'http://csrc.nist.gov/ns/oscal/1.0 ../../../../../xml/schema/oscal_catalog_schema.xsd'"
```

--------------------------------

### Convert OSCAL JSON Catalog to XML with Literal JSON Input

Source: https://github.com/usnistgov/oscal/blob/main/build/README.md

This command allows passing the JSON content directly as a literal string using the 'json' runtime parameter, which can be useful for programmatic invocation. Adjust quote marks as necessary for your shell.

```bash
java -jar "saxon10he.jar" -xsl:"oscal_catalog_json-to-xml-converter.xsl" -o:"oscal-catalog.xml" -it:from-json json="{ \"catalog\": {} }"
```