Updated core documentation.

Integrated metaschema-java add/remove methods.

CODEMETA.yaml

@@ -0,0 +1,15 @@
+
+---
+categories:
+  - tools
+
+themes:
+  - Information Technology
+    - Data and informatics
+    - Data entry
+  - Manufacturing
+    - Systems engineering
+    - Systems integration
+    - Technology commercialization
+  - Mathematics and Statistics
+    - Modeling and simulation research

CODEOWNERS

@@ -0,0 +1,9 @@
+# This file lists the contributors responsible for the
+# repository content. They will also be automatically
+# asked to review any pull request made in this repository.
+
+# Each line is a file pattern followed by one or more owners.
+# The sequence matters: later patterns take precedence.
+
+# FILES  OWNERS
+*        @david-waltermire-nist

CONTRIBUTING.md

@@ -1,16 +1,31 @@
-# Contributing to the Metaschema Project
-
-This page is for potential contributors to this project. It provides basic information on the project, describes the main ways people can make contributions, explains how to report issues relating to the project and projecta rtifacts, and lists pointers to additional sources of information.
+- [Overview](#overview)
+  - [Project approach](#project-approach)
+  - [Making Contributions](#making-contributions)
+  - [Issue reporting and handling](#issue-reporting-and-handling)
+  - [Contributing to this GitHub repository](#contributing-to-this-github-repository)
+    - [Repository structure](#repository-structure)
+  - [Contributing to Development](#contributing-to-development)
+    - [User Stories](#user-stories)
+    - [Reporting User Story Status](#reporting-user-story-status)
+    - [Project Status](#project-status)
+  - [Communications mechanisms](#communications-mechanisms)
+- [Licenses and attribution](#licenses-and-attribution)
+  - [This project is in the public domain](#this-project-is-in-the-public-domain)
+  - [Contributions will be released into the public domain](#contributions-will-be-released-into-the-public-domain)
+
+# Overview
+
+This page is for potential contributors to this project. It provides basic information on the project, describes the main ways people can make contributions, explains how to report issues relating to the project and project artifacts, and lists pointers to additional sources of information.
 
 ## Project approach
 
-This project uses an agile approach for development, where we focus on implementing the 20% of the functionality that solves 80% of the problem. We’re trying to focus on the core capabilities that are needed to provide the greatest amount of benefit. Because we’re working on a small set of capabilities, this allows us to make very fast progress. We’re building the features that we believe solve the biggest problems to provide the most value. We provide extension points that allow uncovered cases to be supported by others.
+This project uses an agile approach for development, where we focus on implementing the 20% of the functionality that solves 80% of the problem. We’re trying to focus on the core capabilities that are needed to provide the greatest amount of benefit. Because we’re working on a small set of capabilities, this allows us to make very fast progress. We’re building the features that we believe solve the biggest problems first to provide the most value. We provide extension points that allow uncovered cases to be supported by others.
 
-We track our current work items using GitHub [project cards](../../projects). Our active project is typically the lowest numbered open project within the previously referenced page.
+We track our current work items using GitHub project cards in the project's [work board](../../projects/1).
 
 ## Making Contributions
 
-Contributions are welcome to this project repository.
+Contributions of code and documentation are welcome to this repository.
 
 For more information on the project's current needs and priorities, see the project's GitHub issue tracker (discussed below). Please refer to the [guide on how to contribute to open source](https://opensource.guide/how-to-contribute/) for general information on contributing to an open source project.
 
@@ -28,37 +43,41 @@ The project team regularly reviews the open issues, prioritizes their handling,
 This project uses a typical GitHub fork and pull request [workflow](https://guides.github.com/introduction/flow/). To establish a development environment for contributing to the project, you must do the following:
 
 1. Fork the repository to your personal workspace. Please refer to the Github [guide on forking a repository](https://help.github.com/articles/fork-a-repo/) for more details.
-1. Create a feature branch from the master branch for making changes. You can [create a branch in your personal repository](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) directly on GitHub or create the branch using a Git client. For example, the ```git branch working``` command can be used to create a branch named *working*.
+1. Create a feature branch from the `main` branch for making changes. You can [create a branch in your personal repository](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) directly on GitHub or create the branch using a Git client. For example, the ```git branch working``` command can be used to create a branch named *working*.
 1. You will need to make your modifications by adding, removing, and changing the content in the branch, then staging your changes using the ```git add``` and ```git rm``` commands.
-1. Once you have staged your changes, you will need to commit them. When committing, you will need to include a commit message. The commit message should describe the nature of your changes (e.g., added new feature X which supports Y). You can also reference an issue from the project repository by using the hash symbol. For example, to reference issue #34, you would include the text "#34". The full command would be: ```git commit -m "added new feature X which supports Y addressing issue #34"```.
+1. Once you have staged your changes, you will need to commit them. When committing, you will need to include a commit message. The commit message should describe the nature of your changes (e.g., added new feature X which supports Y). You can also reference an issue from the OSCAL repository by using the hash symbol. For example, to reference issue #34, you would include the text "#34". The full command would be: ```git commit -m "added new feature X which supports Y addressing issue #34"```.
 1. Next, you must push your changes to your personal repo. You can do this with the command: ```git push```.
 1. Finally, you can [create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/).
+    - Please allow the NIST OSCAL maintainers to make changes to your pull request, to efficiently merge it, by selecting on your fork the setting to [always allow edits from the maintainers](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork).
+    - Review [the OSCAL release and versioning strategy](./versioning-and-branching.md) and [choose the base branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request) accordingly. Normally, you should target the `develop` branch or a `release-x.y` as the base branch unless asked to use a different branch. Please select the appropriate branch before requesting a review from a maintainer so delays in approving your pull request are avoided.
 
 ### Repository structure
 
-This repository consists of the following directories and files pertaining to the project:
+This repository consists of the following directories and documentation files pertaining to the project:
 
-- [.github](.github): Contains GitHub issue and pull request templates for the project.
-[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md): This file contains a code of conduct for all project contributors.
+- [.github](.github): Contains GitHub issue and pull request templates, and GitHub action workflows for the project.
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md): This file contains a code of conduct for all project contributors.
 - [CONTRIBUTING.md](CONTRIBUTING.md): This file is for potential contributors to the project. It provides basic information on the project, describes the main ways people can make contributions, explains how to report issues, and lists pointers to additional sources of information. It also has instructions on establishing a development environment for contributing to the project and using GitHub project cards to track development sprints.
 - [LICENSE.md](LICENSE.md): This file contains license information for the files in this GitHub repository.
 - [USERS.md](USERS.md): This file explains which types of users are most likely to benefit from use of this project and its artifacts.
 
-## Contributing to a Development Sprint
+All other files and directories are related to the Java code managed in this repository.
+
+## Contributing to Development
 
-This project is using the GitHub [project cards](../../projects) feature to track development sprints as part of the core project work stream. A typical development sprint lasts roughly a month, with some sprints lasting slightly less or more to work around major holidays or events attended by the core project team. The active sprint is typically the lowest numbered open project within the previously referenced page.
+This project is using the GitHub project cards feature in the project's [work board](../../projects/1) to track development as part of the core project work stream.
 
 ### User Stories
 
-Each development sprint consists of a set of [user stories](../../issues?q=is%3Aopen+is%3Aissue+label%3A%22User+Story%22), that represent features, actions, or enhancements that are intended to be developed during the sprint. Each user story is based on a [template](../../issues/new?template=feature_request.md&labels=enhancement%2C+User+Story) and describes the basic problem or need to be addressed, a set of detailed goals to accomplish, any dependencies that must be addressed to start or complete the user story, and the criteria for acceptance of the contribution.
+Development is done against a set of [user stories](../../issues?q=is%3Aopen+is%3Aissue+label%3A%22User+Story%22), that represent features, actions, or enhancements that are intended to be developed. Each user story is based on a [template](../../issues/new?template=feature_request.md&labels=enhancement%2C+User+Story) and describes the basic problem or need to be addressed, a set of detailed goals to accomplish, any dependencies that must be addressed to start or complete the user story, and the criteria for acceptance of the contribution. Each user story is organized against a developmental [milestone](../../milestones), indicating the release for which the user story is planned to be addressed.
 
 The goals in a user story will be bulleted, indicating that each goal can be worked on in parallel, or numbered, indicating that each goal must be worked on sequentially. Each goal will be assigned to one or more individuals to accomplish.
 
-Note: A user story that is not part of a specific development sprint can still be worked on at any time by any project contributor. When a user story is not assigned to sprint, its status will not be tracked as part of our sprint management efforts, but when completed will still be considered as a possible contribution to the project.
+Note: A user story that is not part of a specific milestone can still be worked on at any time by any project contributor.
 
 ### Reporting User Story Status
 
-When working on a goal that is part of a user story you will want to provide a periodic report on any progress that has been made until that goal has been completed. This status must be reported as a comment to the associated user story issue. For a user story that is part of a development sprint, status reports will typically be made by close of business the day before the weekly status meeting. Progress on goals in each issue will be tracked by the NIST leads and will be used to update the project cards for the current sprint.
+When working on a goal that is part of a user story you will want to provide a periodic report on any progress that has been made until the user story's goal(s) have been completed. This status is reported as a comment to the associated user story issue. Progress on goals in each issue will be tracked by the repository maintainers and will be used to update the project cards for the current sprint.
 
 When describing any open issues encountered use an "\@mention" of the individual who needs to respond to the issue. This will ensure that the individual is updated with this status. Please also raise any active, unresolved issues on the weekly status calls.
 
@@ -76,10 +95,14 @@ Note: A pull request must be submitted for all goals before an issue will be mov
 
 ## Communications mechanisms
 
-There are two mailing lists for the OSCAL project, for which this project supports:
+This project originated as part of the [Open Security Controls Assessment Language](https://pages.nist.gov/OSCAL/) (OSCAL) project. We use the OSCAL communications channels for this project as well.
+
+A Gitter [chat room](https://gitter.im/usnistgov-OSCAL/Lobby) is available for OSCAL-related discussions. This is a great place to discuss issues pertaining to this work with the community. The NIST OSCAL team actively chats on the OSCAL Gitter. This room is also setup with Github integration, which provides a good summary of recent Github repo activities within the chat room.
+
+There are two OSCAL mailing lists, which are also used for this project.
 
-- *oscal-dev@nist.gov* for communication among parties interested in contributing to the development of OSCAL or exchanging ideas. Subscribe by sending an email to [oscal-dev-join@nist.gov](mailto:oscal-dev-join@nist.gov). To unsubscribe send an email to [oscal-dev-leave@nist.gov](mailto:oscal-dev-leave@nist.gov).
-- *oscal-updates@nist.gov* for low-frequency updates on the status of the OSCAL project. Subscribe by sending an email to [oscal-updates-join@nist.gov](mailto:oscal-updates-join@nist.gov). To unsubscribe send an email to [oscal-updates-leave@nist.gov](mailto:oscal-updates-leave@nist.gov).
+- **OSCAL Developer List:** [oscal-dev@list.nist.gov](mailto:oscal-dev@list.nist.gov) for communication among parties interested in contributing to the development of OSCAL or exchanging ideas. Subscribe by sending an email to [oscal-dev+subscribe@list.nist.gov](mailto:oscal-dev+subscribe@list.nist.gov). To unsubscribe send an email to [oscal-dev+unsubscribe@list.nist.gov](mailto:oscal-dev+unsubscribe@list.nist.gov).
+- **OSCAL Updates List:** [oscal-updates@list.nist.gov](mailto:oscal-updates@list.nist.gov) for low-frequency updates on the status of the OSCAL project. Subscribe by sending an email to [oscal-updates+subscribe@list.nist.gov](mailto:oscal-updates+subscribe@list.nist.gov). To unsubscribe send an email to [oscal-updates+unsubscribe@list.nist.gov](mailto:oscal-updates+unsubscribe@list.nist.gov).
 
 # Licenses and attribution
 

README.md

@@ -1,2 +1,50 @@
 # liboscal-java
-A Java library to support processing OSCAL content
+
+A Java library to support processing OSCAL content.
+
+This open-source, Metaschema Java library offers a programatic means to work with [OSCAL](https://pages.nist.gov/OSCAL/) models defined by the [Metaschema modeling language](https://github.com/usnistgov/metaschema). This framework also supports programatically creating, modifying, parsing, and writing XML, JSON, and YAML OSCAL instance data. This work is intended to make it easier for Java software developers to incorporate OSCAL-based capabilities into their applications.
+
+This library is based on the [Metaschema Java Tools](https://pages.nist.gov/metaschema-java/) project.
+
+This effort is part of the National Institute of Standards and Technology (NIST) OSCAL Program.
+
+## Contributing to this code base
+
+Thank you for interest in contributing to the Metaschema Java framework. For complete instructions on how to contribute code, please read through our [CONTRIBUTING.md](CONTRIBUTING.md) documentation.
+
+## Public domain
+
+This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Using as a Maven dependency
+
+This project's modules are published to [Maven Central](https://search.maven.org/search?q=g:gov.nist.secauto.oscal.liboscal-java).
+
+You can include these artifacts in your Maven POM as a dependency.
+
+## Building
+
+This project can be built with [Apache Maven](https://maven.apache.org/) version 3.8.4 or greater.
+
+The following instructions can be used to clone and build this project.
+
+1. Clone the GitHub repository.
+
+```bash
+git clone --recurse-submodules https://github.com/usnistgov/liboscal-java.git 
+```
+
+2. Build the project with Maven
+
+```bash
+mvn install
+```
+
+## Contact us
+
+Maintainer: [David Waltermire](https://www.nist.gov/people/david-waltermire) - [@david-waltermire-nist](https://github.com/david-waltermire-nist), [NIST](https://www.nist.gov/) [Information Technology Labratory](https://www.nist.gov/itl), [Computer Security Division](https://www.nist.gov/itl/csd), [Security Components and Mechanisms Group](https://www.nist.gov/itl/csd/security-components-and-mechanisms)
+
+Email us: [oscal@nist.gov](mailto:oscal@nist.gov)
+
+Chat with us: [Gitter usnistgov-OSCAL/Lobby](https://gitter.im/usnistgov-OSCAL/Lobby)
+