From 557d7c53ff2a66a4b192583011ab343957f3faf1 Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Tue, 27 Jun 2023 17:32:36 -0400 Subject: [PATCH] More improvements to top-level docs --- CODEMETA.yaml | 317 +++++++++++++++++++++++++++++++++++++++++++++ CODEOWNERS | 9 ++ CODE_OF_CONDUCT.md | 2 + CONTRIBUTING.md | 124 ++++++------------ README.md | 117 ++++++++++++----- 5 files changed, 451 insertions(+), 118 deletions(-) create mode 100644 CODEMETA.yaml create mode 100644 CODEOWNERS diff --git a/CODEMETA.yaml b/CODEMETA.yaml new file mode 100644 index 00000000..488d3c72 --- /dev/null +++ b/CODEMETA.yaml @@ -0,0 +1,317 @@ +# Topics for the NIST Open Source Portal +# +# Set the topic tags for your open source repository from the nested +# list below. Un-comment the relevant lines: +# +# remove the `#` character *and* the space immediately after it +# +# so that the YAML syntax remains valid. You may delete everything +# that does not apply, and add new topics from the NIST Taxonomy +# +# +# For example, a valid version of this file would be (note the `:` +# and `---`, they are important!) as follows: +# +# --- +# categories: +# - scientific-software +# +# themes: +# - Information Technology +# - Software research +# - Software performance +# +# Since scientific-software is most common it is left as the default +# category. Feel free to comment it with a hash (#) if it does not +# apply. There is no default theme; select as many as are relevant. +# Make sure to remove unwanted categories as the final topics are +# produced from this file. + +--- +categories: + # - ai-ml + # - performance-and-workflow + # - scientific-software + # - simulation + - tools + # - visualization + +themes: + - Information Technology + - Data and informatics + # - Advanced communications + # - Optical communications + # - Quantum communications + # - Wireless (RF) + # + # - Bioscience + # - Biomaterials + # - Biomolecular characterization + # - Bioprocessing + # - Cell biology + # - Engineering or synthetic biology + # - Genomics + # - Glycomics + # - Metabolomics + # - Microbial measurements + # - Proteomics + # + # - Buildings and Construction + # - Heating, ventilation and air conditioning equipment + # - Building codes and standards + # - Building control systems + # - Building damage and repair + # - Building economics + # - Building materials + # - Indoor air quality + # - Resilient buildings + # - Structural engineering + # - Sustainable buildings + # + # - Chemistry + # - Analytical chemistry + # - Chemical engineering and processing + # - Chemical thermodynamics and chemical properties + # - Molecular characterization + # - Theoretical chemistry and modeling + # - Thermochemical properties + # + # - Electronics + # - Electromagnetics + # - Flexible electronics + # - Magnetoelectronics + # - Optoelectronics + # - Organic electronics + # - Semiconductors + # - Sensors + # - Superconducting electronics + # + # - Energy + # - Alternative energy + # - Conventional energy + # - Electric power and smart grid + # - Energy efficiency + # - Fuels + # - Sustainability + # + # - Environment + # - Air, soil and water quality + # - Environmental health + # - Greenhouse gas measurements + # - Marine science + # + # - Fire + # - Emergency building evacuation + # - Fire detection + # - Fire dynamics and science + # - Fire fighting + # - Fire modeling + # - Fire risk reduction + # - Materials flammability + # - Structural fire resistance + # - Wildland-Urban interface fire + # + # - Forensic Science + # - Ballistics + # - Digital evidence + # - DNA and biological evidence + # - Drugs and toxicology + # - Fingerprints and pattern evidence + # - Trace evidence + # + # - Health + # - Clinical diagnostics + # - Dentistry + # - Food and nutrition + # - Medical imaging + # - Pharmaceuticals + # - Precision medicine + # - Regenerative medicine + # + # - Information Technology + # - Artificial intelligence + # - Biometrics + # - Cloud computing and virtualization + # - Complex systems + # - Computational science + # - Conformance testing + # - Cyber-physical systems + # - Smart cities + # - Cybersecurity + # - Configuration and vulnerability management + # - Cryptography + # - Cybersecurity Education and Workforce Development + # - Risk management + - Data and informatics + # - Human language technology + - Information retrieval + # - Natural language processing + # - Data entry + # - Federal information standards (FIPS) + # - Health IT + # - Identity and access management + # - Internet of Things (IoT) + # - Interoperability testing + # - Mobile + # - Networking + # - Mobile and Wireless Networking + # - Network Management and Monitoring + # - Network Modeling and Analysis + # - Network Security and Robustness + # - Network Test and Measurement + # - Next Generation Networks + # - Protocol Design and Standardization + # - Software-defined and virtual networks + # - Privacy + # - Software research + # - Software assurance + # - Software performance + # - Software testing + # - Usability and human factors + # - Accessibility + # - Video analytics + # - Visualization research + # - Voting systems + # + # - Infrastructure + # + # - Manufacturing + # - Additive manufacturing + # - Biomanufacturing + # - Factory communications + # - Factory operations planning and control + # - Interoperability in manufacturing + # - Machining + # - Manufacturing systems design and analysis + # - Monitoring, diagnostics and prognostics + # - Process improvement + # - Process measurement and control + # - Product data + # - Quality assurance + # - Robotics in manufacturing + # - Agility and adaptability + # - Collaborative robots + # - Dexterous grasping + # - Industrial autonomous vehicles + # - Mobile manipulators + # - Navigation, actuation and control + # - Sensing and perception + # - Supply chain + # - Sustainable manufacturing + # - Systems engineering + # - Systems integration + # - Technology commercialization + # + # - Materials + # - Ceramics + # - Composites + # - Concrete and cement + # - Materials characterization + # - Composition and structure + # - Magnetic properties + # - Mechanical properties + # - Thermal properties + # - Metals + # - Modeling and computational material science + # - Polymers + # - Superconductors + # + # - Mathematics and Statistics + # - Experiment design + # - Image and signal processing + # - Mathematical knowledge management + # - Modeling and simulation research + # - Numerical methods and software + # - Statistical analysis + # - Uncertainty quantification + # + # - Metrology + # - Acoustic/vibration metrology + # - Amount of substance + # - Dimensional metrology + # - Electrical and electromagnetic metrology + # - Flow metrology and rheology + # - Force metrology + # - Humidity metrology + # - Ionizing radiation metrology + # - Mass metrology + # - Metric + # - Optical, photometry and laser metrology + # - Pressure and vacuum metrology + # - Thermometry metrology + # - Time and frequency metrology + # - Weights and measures + # + # - Nanotechnology + # - Nanobiotechnology + # - Nanochemistry + # - Nanoelectronics + # - Nanofabrication/manufacturing + # - Lithography + # - Self-assembly + # - Nanofluidics + # - Nanomagnetics + # - Nanomaterials + # - Nanomechanics + # - Nanometrology + # - Nanophotonics + # - Nanophysics + # - Nanoplasmonics + # + # - Neutron research + # + # - Performance excellence + # - Assessment tools and services + # - Baldrige Award + # - Baldrige Examiners + # - Baldrige framework and criteria + # - Best practices + # - Leadership development + # + # - Physics + # - Atomic, molecular and quantum + # - Biological physics + # - Condensed matter + # - Electron physics + # - Magnetics + # - Nuclear physics + # - Optical physics + # - Quantum information science + # - Radiation + # - Spectroscopy + # - Thermodynamics + # - Time and frequency + # + # - Public safety + # - Chemical, Biological, Radiological, Nuclear and Explosives (CBRNE) + # - First responder preparedness + # - Law enforcement + # - Physical security + # - Public safety communications research + # - Response robots + # - Aerial + # - Aquatic and underwater + # - Ground + # + # - Resilience + # - Community resilience + # - Disaster and failure studies + # - Earthquake risk reduction + # - Resilient materials + # - Windstorm impact reduction + # + - Standards + # - Accreditation + # - Calibration Services + # - Conformity assessment + - Documentary standards + - Frameworks + # - Reference data + - Reference instruments + # - Reference materials + # - Standards education + # + # - Transportation + # - Aerospace + # - Automotive + # - Rail diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 00000000..658c0805 --- /dev/null +++ b/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 +* @wendellpiez @usnistgov/itl-metaschema diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index a9d87b75..1447980b 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,5 +1,7 @@ # Contributor Covenant Code of Conduct +The following is offered as standard code of conduct to which all contributors are assumed to be committed. + ## Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39ec0ca4..c86b4316 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,84 +1,78 @@ -# Contributing to the Metaschema Project +- [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. - -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. ## Issue reporting and handling -All requests for changes and enhancements to the repository are initiated through the project's [GitHub issue tracker](../../issues). To initiate a request, please [create a new issue](https://help.github.com/articles/creating-an-issue/). The following issue templates exist for creating a new issue: -* [User Story](../../issues/new?template=feature_request.md&labels=enhancement%2C+User+Story): Use to describe a new feature or capability to be added to the project. -* [Defect Report](../../issues/new?template=bug_report.md&labels=bug): Use to report a problem with an existing feature or capability. -* [Question](../../issues/new?labels=question&template=question.md): Use to ask a question about the project or the contents of the repository. +All requests for changes and enhancements to the repository are initiated through the project's [GitHub issue tracker](../../issues). To initiate a request -The project team regularly reviews the open issues, prioritizes their handling, and updates the issue statuses, proving comments on the current status as needed. +- [Create a new issue](https://help.github.com/articles/creating-an-issue/). ## Contributing to this GitHub repository 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. 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. Next, you must push your changes to your personal repo. You can do this with the command: ```git push```. +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 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. ### Repository structure -This repository consists of the following directories and 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. -- [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. - -## Contributing to a Development Sprint - -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. - -### 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. +This repository consists of the following directories and documentation files pertaining to the project: -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. +- [.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. -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. +All other files and directories are related to the XSLT codebase managed in this repository. -### Reporting User Story Status +## Contributing to Development -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. +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. -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. - -### Project Status - -The project cards for each sprint will be in one of the following states: +## Communications mechanisms -- "To do" - The user story has been assigned to the sprint, but work has not started. -- "In progress" - Work has started on the user story, but development of the issue has not completed. -- "Review in Progress" - All goals for the user story have been completed and one or more pull requests have been submitted for all associated work. The NIST team will review the pull requests to ensure that all goals and acceptance criteria have been met. -- "Reviewer Approved" - All reviews of a pull request related to a user story have been completed. The pull request still needs to be merged. -- "Done" - Once the contributed work has been reviewed and the pull request has been merged, the user story will be marked as "Done". +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. -Note: A pull request must be submitted for all goals before an issue will be moved to the "under review" status. If any goals or acceptance criteria have not been met, then the user story will be commented on to provide feedback, and the issue will be returned to the "In progress" state. +A Gitter [chat room](https://gitter.im/usnistgov-OSCAL/metaschema) is available for Metaschema-related discussions. This is a great place to discuss issues pertaining to this work with the community working with Metaschema. 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. -## Communications mechanisms +There are two OSCAL mailing lists, which may also be used for this project. -This project originated as part of the Open Security Controls Assessment Language (OSCAL) project. We are still using the OSCAL lists for this project. There are two mailing lists for the project: +- **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). -- *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). +Note that the contact points offered above are subject to change without notice. # Licenses and attribution @@ -91,39 +85,3 @@ This project is in the public domain within the United States, and copyright and ## Contributions will be released into the public domain All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest. - -## Git Client Setup - -### Initializing Git submodules - -This GitHub repository makes use of Git submodules to mount other repositories as subdirectories. - -When cloning this repo for the first time, you need to initialize the submodules that this repository depends on. To do this you must execute the following command: - -``` -git submodule update --init -``` - -You can perform the clone and submodule initialization in a single step by using the following command: - -``` -git clone --recurse-submodules https://github.com/usnistgov/metaschema.git -``` - -### Configuring Submodules to Use SSH - -Some clients will make use of Git over SSH with a private SSH key for GitHub projects. For convenience, the submodules are configured to use HTTP instead of SSH. To override this default behavior, you will need to configure your Git client to use SSH instead of HTTP using the following command: - -``` -git config --global url."git@github.com:".insteadOf https://github.com/ -``` - -This instructs your Git client to dynamically replace the HTTP-based URLs with the proper SSH URL when using GitHub. - -### Updating submodules - -Submodule contents will be periodically updated. To ensure you have the latest commits for a configured submodule, you will need to run the following command: - -``` -git submodule update --init --recursive -``` diff --git a/README.md b/README.md index edbb6f1f..44e56260 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,128 @@ # metaschema-xslt +## punchlist + +- [x] `CODEMETA` +- [x] `CONTRIBUTING.md` +- [x] `CODEOWNERS` +- [x] `LICENSE.md` +- [x] `CODE_OF_CONDUCT.md` +- [x] this file (see outline/requirements at end) + ## Software description -Metaschema-XSLT is an XSLT-based implementation of the NIST [Metaschema document modeling framework](https://github.com/usnistgov/metaschema). +Metaschema-XSLT is an XSLT-based implementation of the NIST (ITL/CSD) [Metaschema document modeling framework](https://github.com/usnistgov/metaschema). NIST Metaschema defines how to describe sets of data objects -- serialized information sets, considered abstractly -- *across* and *between* implementations of processing systems that are coded to manipulate and process such objects. -These descriptions are provided by means of a formal *language* developed for this purpose. An instance of this language is called a metaschema, while the language is named Metaschema. A metaschema proposes or stipulates, by description, a model or set of models, which can be followed by data instances in data processing systems using standard formats and notations, such as XML, JSON and YAML. (This particular implementation supports XML- and JSON-based notations.) Because the Metaschema definitions are abstracted away from details of the system, data sets conformant to these models (and thereby pre-fitted for operations that leverage them) can be developed, validated externally and readily processed by first, second or third parties to contracts. Prior knowledge to make informed and 'intelligent' inferences regarding information sets is provided by metaschema definitions, while metaschema-based tools can test for and enforce the constraints that come with Metaschema data (type) definitions. - -In support of metaschemas defined using this language, this software can be used to generate utilities and software artifacts including XML Schema (XSD) and JSON Schema, data conversion scripts, and model documentation. All of these can be deployed in support of other technologies addressing requirements in this domain. +These descriptions are provided by means of a formal *language* developed for this purpose. In support of metaschemas defined using this language, this software can be used to generate utilities and software artifacts including XML Schema (XSD) and JSON Schema, data conversion scripts, and model documentation. ### Statement of purpose -NIST ITL/CSD Metaschema is a data modeling technology, which works by providing formal and validable descriptions of data models such that they can be cast and rewritten in various alternative syntaxes, i.e. optimized at the level of format, while permitting lossless conversion of defined-as-equal information sets across format boundaries. +NIST ITL/CSD Metaschema is a data modeling technology, which works by providing formal and validable descriptions of data models such that instances (data sets) conforming to these models can be cast and rewritten in various alternative syntaxes, i.e. optimized at the level of format, while permitting lossless conversion of defined-as-equal information sets across format boundaries. -The software in this repository began as a 'scaffolding' demonstration and proof-of-concept of the capabilities of the Metaschema language, as an instance and demonstration of this concept. However, the Metaschema language is also defined in such a way as to be distinct from and independent of software that implements it. As such, by standing as a functional demonstration of metaschema capabilities, this software can serve in appropriate contexts +In addition to neutralizing the "XML/JSON" or more broadly "Markup/object notation" boundary, this technology also offers other capabilities such as external specification and validation of application-oriented semantics ("business rules") of models appropriate to specialized knowledge domains. -Accordingly, the current effort seeks not only to implement, demonstrate and enable the capabilities of a NIST Metaschema system, with respect to functionalities including schema generation, data conversion or pipelining, stylesheet generation or a host of other potential uses of Metaschema and metaschemas considered broadly. In addition, we aspire to do so sustainably, not in the sense that the software will work forever, but that its users and adopters will at all times be able to trace the data flows it supports. +The current effort seeks to implement, demonstrate and enable the capabilities of a NIST Metaschema system, with respect to functionalities including schema generation, data conversion or pipelining, stylesheet generation or a host of other potential uses of Metaschema and metaschemas considered broadly. In addition, we aspire to do so sustainably, not in the sense that the software will meet all requirements for all time, but that it will be reliable, validable and traceable. -Considering data traceability and process transparency as the primary goal makes secondary goals, such as the creation of use cases (for this and compatible software) and the codification and maturation of relevant standards, including standards supported by Metaschema such as OSCAL. +Considering data traceability and process transparency as primary goals will also serve secondary goals, such as the creation and demonstration of use cases (for this and compatible software) and the codification and maturation of relevant standards, including standards supported by Metaschema such as OSCAL. Stress is therefore on: - Transparency, testability and maintainability of processing on an open-source stack -- Generality of support of Metaschema features - Conformance in support of Metaschema-based data interchange / interop +- Generality of support of Metaschema features What we do not emphasize: - Performance -- Portability beyond the XML/XSLT dependency stack (instead see other Metaschema initiatives) -- Use cases (only) +- Portability beyond the XML/XSLT dependency stack (instead we relying on other Metaschema initiatives) +- Use cases in isolation ### Origins -Formerly housed in the Metaschema repository, this code base traces the history of development of the Metaschema concept in the context of the OSCAL project. It was originally conceived as a demonstration and proof of concept, providing a bridge enabling JSON- and XML-based development in parallel over common problem sets. Success in this effort led to a determination that multiple implementations of a platform-independent specification were needed, at which point this implementation was carved out into its own repository. +Formerly housed in the Metaschema repository, this code base traces the history of development of the Metaschema concept in the context of the OSCAL project. It was originally conceived as a demonstration and proof of concept, providing a bridge enabling JSON- and XML-based development in parallel over common problem sets. Success in this effort led to a determination that multiple implementations of a platform-independent specification were needed, at which point this implementation was carved out into its own repository. + +### Licensing + +See the [project license](LICENSE.md) on this site. + +This project is placed into the world wide public domain. ### Project sunset Currently there is no plan to continue maintaining this project or code base beyond the retirement of its lead researcher. Indeed a project goal is to enable the stabilization and socialization of the Metaschema technology, as evidenced by the use and support of *other* Metaschema implementations. -### Description of the repository contents +## Repository contents `src` includes XSLT source code, with supporting infrastructure including ad-hoc testing `support` includes dependent submodules -### Installation and use +## Installation and use -The software is designed to be used in any of a range of ways: +The software is designed to be used in a range of ways: -- Dynamically, in development of metaschemas and Metaschema-based software and tools -- Within CI/CD, to generate artifacts or productions from metaschema source under controlled conditions +- Directly, in development of metaschemas and Metaschema-based software and tools +- Within Metaschema-based builds, including under CI/CD, to generate artifacts or productions from metaschema source under controlled conditions -Accordingly, there will generally be multiple points of entry or invocation methods for any process, with the software dependencies maintained as appropriate for different use cases. +Accordingly (as is not uncommon with XML/XSLT-based libraries), there will generally be multiple points of entry or invocation methods for any process, with the software dependencies maintained as appropriate for different use cases. This being the case, since the applications are written in XSLT 3.0, the latest stable version of the [Saxon](https://saxonica.com/documentation11/documentation.xml) processor is regarded as the primary dependency. At one extreme, an XML IDE such as oXygen XML (or extended VS Code), integrating Saxon, can be used to run processes and tests in diagnostic mode, using its runtime and interfaces for XSLT (`*.xsl`) or XProc (`*.xproc`). -At the other, command-line scripts or makefiles can be used to automate processes to run externally to produce outputs, and the repository includes examples of these. +At the other, command-line scripts or makefiles can be used to automate processes to run externally to produce outputs. The repository includes examples of these. -In this case, a convenient way to manage dependencies is to use Maven to manage a Java-based stack deploying SaxonHE and/or XML Calabash, as open-source XML processors. Scripts are provided for running under Maven. +In particular, a convenient way to manage dependencies is to use Maven to manage a Java-based stack deploying SaxonHE and/or XML Calabash, as open-source XML processors. Scripts are provided for running under Maven. -#### To run +### To run With `bash` and Maven installed, run any script given at the top level. Use `--help` for help. For testing, all XSpec scenarios (`*.xspec`) can be run in place to generate local test reports. +### Dependencies + +As noted, the Saxon XSLT engine can be regarded as a *de facto* dependency - while this XSLT-conformant code should in principle run in *any* processor implementing the language. SaxonHE can be bundled using Maven or another Java packaging technology. + +Developers interested in demonstrating the viability of these processes in different processors and environments are eagerly invited to participate in development of this tool or [related tools](#Related_projects). + + +### Git Client Setup + +See more on git setup on the page on [Contributing](CONTRIBUTING). + +Clone the project: + +``` +git clone --recurse-submodules https://github.com/usnistgov/metaschema-xslt.git +``` + +Or to clone with submodule initialization: + +``` +git clone --recurse-submodules https://github.com/usnistgov/metaschema-xslt.git +``` + +### Initializing Git submodules + +This GitHub repository makes use of Git submodules to mount other repositories as subdirectories. When cloning this repo for the first time, you need to initialize these. + +``` +git submodule update --init +``` + +Or do this in one step using `clone --recurse-submodules` as noted. + +### Updating submodules + +Submodule contents will be periodically updated. To ensure you have the latest commits for a configured submodule, you will need to run the following command: + +``` +git submodule update --init --recursive +``` + ## Contact information Principal Investigator: Wendell Piez, NIST ITL/CSD (Information Technology Laboratory, Computer Security Division). Email w e n d e l l (dot) p i e z (at) n i s t (dot) g o v. @@ -77,7 +131,11 @@ This initiative spins off from and supports the ITL/CSD [Metaschema](https://pag For OSCAL-related discussions see the [OSCAL Site](https://pages.nist.gov/OSCAL/contribute). -## Related Material +## Cite this work + +Piez, Wendell (2023), Metaschema-XSLT. US National Institute of Standards and Technology (NIST). https://github.com/usnistgov/metaschema-xslt. + +## Related projects See the [Metaschema Repository](https://github.com/usnistgov/metaschema) and its [Pages Site](https://pages.nist.gov/metaschema/) for a description and specification of the technology this software is designed to support. @@ -89,24 +147,13 @@ Projects in support of NIST Metaschema (at time of writing) - https://github.com/usnistgov/metaschema-node - https://github.com/usnistgov/nmetaschema -Using NIST Metaschema +Projects currently known to be using NIST Metaschema - [OSCAL: the Open Security Controls Assessment Language](https://pages.nist.gov/OSCAL/) - -## Cite this work - -Piez, Wendell (2023), Metaschema-XSLT. US National Institute of Standards and Technology (NIST). https://github.com/usnistgov/metaschema-xslt. - -## Dependencies - -As noted above, the Saxon XSLT engine can be regarded as a *de facto* dependency - while this XSLT-conformant code should in principle run in *any* processor implementing the language. SaxonHE can be bundled using Maven as noted above. This makes Maven (and Java) the dependency for practical purposes. - -Developers interested in demonstrating the viability of these processes in different processors and environments are eagerly invited to participate. - ## Required outline -See https://raw.githubusercontent.com/usnistgov/opensource-repo/main/README.md +This page includes all the following, as described by guidelines at https://raw.githubusercontent.com/usnistgov/opensource-repo/main/README.md 1. Software or Data description - Statements of purpose and maturity