From 84b1cb7f4116020099ac18ffd40668da25a3cd9d Mon Sep 17 00:00:00 2001 From: Alexander Stein Date: Fri, 16 Dec 2022 11:17:36 -0500 Subject: [PATCH 1/2] Create tutorial landing page and move tutorial. --- build/config/.lycheeignore | 3 +- .../tutorials/1-getting-started/_index.md | 954 ++++++++++++++++++ website/content/tutorials/_index.md | 11 + website/content/use/_index.md | 2 +- website/static/img/computer.svg | 874 ++++++++++++++++ website/static/img/computer_numbered.svg | 927 +++++++++++++++++ website/themes/uswds | 2 +- 7 files changed, 2770 insertions(+), 3 deletions(-) create mode 100644 website/content/tutorials/1-getting-started/_index.md create mode 100644 website/content/tutorials/_index.md create mode 100644 website/static/img/computer.svg create mode 100644 website/static/img/computer_numbered.svg diff --git a/build/config/.lycheeignore b/build/config/.lycheeignore index 3766a9c09..1db8e38f7 100644 --- a/build/config/.lycheeignore +++ b/build/config/.lycheeignore @@ -1 +1,2 @@ -https://search.usa.gov/search \ No newline at end of file +https://search.usa.gov/search +http://csrc.nist.gov/ns/oscal/metaschema/1.0 diff --git a/website/content/tutorials/1-getting-started/_index.md b/website/content/tutorials/1-getting-started/_index.md new file mode 100644 index 000000000..e3f14b7f1 --- /dev/null +++ b/website/content/tutorials/1-getting-started/_index.md @@ -0,0 +1,954 @@ +--- +title: "Getting Started with Metaschema" +Description: "" +heading: Getting Started with Metaschema +toc: + enabled: true +--- + +## Understanding the Domain and Designing the Model + +Metaschema is a framework for consistently organizing information into machine-readable data formats. For example, if we want to build tools to exchange information about computers, how do we represent a computer in a data format? How do we design it to be consistent and reusable across different software? How do we benefit from the right amout of structured information about computers in that format? + +To start organizing this information consistently, we need to consider our mental model of what a computer is. We have to think of the different parts of a computer, sub-parts, and how to compose those parts into a whole. Let's consider a computer such as one visualized below. + +!["Exploded view of a personal computer, unlabeled" from Wikipedia, as created by Gustavb, and published under the Creative Commons Attribution-Share Alike 3.0 Unported license](/img/computer.svg) + +Source: [Wikipedia](https://commons.wikimedia.org/wiki/File:Personal_computer,_exploded_5,_unlabeled.svg) + +In Metaschema terms, this design process is making an [information model](/specification/concepts/terminology/#information-model) for a [managed object](/specification/concepts/terminology/#managed-object), the computer, into [a data model](/specification/concepts/terminology/#data-model) within the [domain](/specification/concepts/terminology/#domain) of computing. And once we understand the required information structure for the computer in this domain, how do we specify a model in Metaschema and what are the benefits? + +## Metaschema Concepts + +Metaschema helps developers to define models once, in a Metaschema definition. The definition specifies the model of information for the managed object in supported machine-readable data formats. A document in such a format is an instance of that definition. A schema can be used to check the instance is well-formed and valid against the definition's specification. + +{{}} + +erDiagram + + "Metaschema definition" }|..|{ "instance" : "must specify model of" + "Metaschema tool" }|..|{ "Metaschema definition" : "must parse" + "Metaschema tool" }|..|{ "instance" : "can parse" + "Metaschema tool" }|..|{ "schema" : "can generate" + "schema" }|..|{ "instance" : "must validate" + +{{}} + +## Basic Modeling and Basic Metaschema Defintions + +We start with an empty Metaschema definition, like the one below, saved in a file called `computer_metaschema.xml`. + +```xml + + + +``` + +Metschema definitions, like the one above, are in XML. A definition begins and ends with capitalized `METASCHEMA` tags. This definition is an empty file, and it is not a valid, well-formed defintion. It is simply the base we will start with. Within those beginning and ending tags, we want to add useful metadata for both developers and Metaschema-enabled tools to consume this definition, like below. + +```xml + + + Computer Model + 0.0.1 + computer + http://example.com/ns/computer + http://example.com/ns/computer + + +``` + +The metadata above provides useful information to to us Metaschema developers and ours tools that parse Metaschema definitions. The `schema-name` is the long-form, descriptive name of the computer model. The `schema-version` is to give the model itself a version number, for either developers or their tools to use. The `short-name` is the shortened form of the `schema-name`. Normally, Metaschema-enabled tools will parse or generate data with this name `computer`, not `Computer Model`. The `namespace` is a URI used to identify the model and its parts as belonging to a single scope for XML data and schemas. Similarly, the `json-base-uri` serves a similar purpose for JSON data and schemas. + +It is important to note this definition is just a starting point. This definition is the most minimally viable definition possible: it is well-formed and valid against [the XML Schema for the Metaschema syntax itself](), but our Metaschema-enabled tools should consider this an empty definition. We have not yet declared a `root-name` and there is no data model yet, so let's start one. We will begin by desinging a computer object to have just an identifier. + +We will now add to the [`assembly`](/specification/concepts/terminology/#assembly) for a computer itself and give it an identifier `flag`. + +```xml + + + Computer Model + 0.0.2 + computer + http://example.com/ns/computer + http://example.com/ns/computer + + Computer Assembly + A container object for a computer, its parts, and its sub-parts. + computer + + Computer Identifier + An identifier for classifying a unique make and model of computer. + + + +``` + +With the definition of the first `assembly` our Metaschema definition takes shape. Firstly, we now add the `root-name` element to identify for Metaschema-enabled tools this `assembly`, whether there are one or more top-level ones defined, is the root element of our data models. This will come in handy later. In the `assembly` declaration, we have defined a `computer` that must have an `id`, and it must the value of it must be a `string`. With Metaschema-enabled tooling, we can have information about a computer like below in their respective JSON, XML, and YAML data formats. + +An instance for the model above is below in JSON, XML, and YAML data formats. + +{{< tabs JSON XML YAML >}} +{{% tab %}} +{{< highlight json >}} +{ + "computer": { + "id": "awesomepc1" + } +} +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight xml >}} + + +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight yaml >}} +--- +computer: + id: awesomepc1 +{{< /highlight >}} +{{% /tab %}} +{{< /tabs >}} + + +At this point, we have our first functional and complete Metaschema definition. When we write Metaschema-enabled tools, they ought to be able to parse this definition and use it to parse one or more instances in JSON, XML, or YAML, as specified in that definition. All three instances above are to be equivalent. + +## Assemblies, Fields, and Flags + +It is important to have a computer with an identifier, but our stakeholders want far more. We can add `field`s and `flag`s for simple key-value properties on a computer and assemblies for more complex objects. We need to continue our design work to understand and specify our information and data models with Metaschema, so we return to modeling once again. + +Let's return to the diagram of the computer before, but now consider how we model the parts of a computer, the sub-parts, and their relationships. Our stakeholders provided us this diagram, and these are the key data points they need our software to process and store. + +!["Exploded view of a personal computer" from Wikipedia, as created by Gustavb, and published under the Creative Commons Attribution-Share Alike 3.0 Unported license](/img/computer_numbered.svg) + +Source: [Wikipedia](https://upload.wikimedia.org/wikipedia/commons/1/13/Personal_computer%2C_exploded_4.svg) + +Below are the parts and sub-parts we want in our information model of a computer in that diagram that our stakeholders require. + +1. Display +1. Motherboard +1. CPU +1. ATA socket +1. Memory +1. Expansion card(s) +1. CD/DVD drive +1. Power supply unit +1. Hard disk +1. Keyboard +1. Mouse + +When we consider the parts and sub-parts, we recognize some hierarchical relationships that we arrange into outline form. + +- Display +- Motherboard + - CPU + - ATA socket + - Memory + - Expansion cards +- CD/DVD drive +- Power supply unit +- Hard disk +- Keyboard +- Mouse + +After discussion with stakeholders of these new data formats, the different stakeholders agree we need to structure additional information about computers, parts, and sub-parts as well. + +- **Computer** + - **Vendor information:** incorporation name; office address; product website + - **Display:** product name; display type + - **Motherboard**: product name; type + - **CPU:** product name; architecture; clock speed + - **ATA socket:** product name; ATA socket type + - **Memory:** product name; size in bytes + - **Expansion cards:** product name; type + - **CD/DVD drive:** product name; type + - **Power supply unit:** product name; wattage; type + - **Hard disk:** product name; capacity; type + - **Keyboard:** product name; type + - **Mouse:** product name; type + +With this outline, we acknowledge there is a hierarchy, and it is important to how we design the managed objects of a computer, especially the motherboard. How can we use Metaschema to encode these hierarchies across data formats? We use assemblies, and within those assemblies, fields and flags in a particular order. + +With an `assembly`, we can specify a complex named object, not just a simple key-value pair. We can annotate this complex named object itself with `flag`s. The object we specify in the assembly can have optional key-values, which we define with `field`s. With these Metaschema concepts, we can enhance the `computer` model to include an `assembly` for a motherboard and include its sub-parts like so. + +```xml + + + Computer Model + 0.0.3 + computer + http://example.com/ns/computer + http://example.com/ns/computer + + Computer Assembly + A container object for a computer, its parts, and its sub-parts. + computer + + Computer Identifier + An identifier for classifying a unique make and model of computer. + + + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Motherboard Assembly + A container object for a motherboard in a computer and its sub-parts. + + + Product Name + The product name from the vendor of the computer part. + + + Motherboard Type + The type motherboard layout, at, atx, mini-itx or an alternative. + + + Motherboard Central Processing Unit (CPU) + The model number of the CPU on the motherboard of a computer. + + + Product Name + The product name from the vendor of the computer part. + + + CPU Architecture + The Instruction Set Architecture (ISA) of the processor, x86, x86-64, arm, or an alternative. + + + CPU Speed + The clock speed of the CPU in megahertz or gigahertz. + + + + + Motherboard Advanced Technology Attachment (ATA) Socket + The model number of ATA socket on the motherboard of a computer. There will only be one socket on any motherboard. + + + Product Name + The product name from the vendor of the computer part. + + + ATA Socket Type + The type of ATA socket on the motherboard , pata (parallel ATA), sata (Serial ATA), or an alternative. + + + + + Motherboard Random Access Memory (RAM) Module(s) + Random access memory hardware installed on the motherboard of a computer. + + + + Product Name + The product name from the vendor of the computer part. + + + Memory Module Size + Size of the memory module in binary, not SI base-10 units, meaning a kilobyte is 1024 bytes, not 1000 bytes. + + + + + Motherboard Expansion Card + The model number of an expansion card connected to the motherboard of a computer. + + + + Product Name + The product name from the vendor of the computer part. + + + Expansion Card Type + The type of expansion card on a motherboard of a computer, such as pci (PCI, e.g. Peripheral Component Interconnect), pcie (PCI Express), or an alternative. + + + + + + + + +``` + +We now have a nested motherboard `assembly` in a computer `assembly` with assorted `flag`s and `field`s to present the important hierarchy of information in the motherboard. With a more detailed model, we can have our Metaschema-enabled tools parse or generate instances. + +An instance for the model above is below in JSON, XML, and YAML data formats. + +{{< tabs JSON XML YAML >}} +{{% tab %}} +{{< highlight json >}} +{ + "computer": { + "id": "awesomepc1", + "vendor": { + "id": "vendor1", + "name": "AwesomeComp Incorportated", + "address": "1000 K Street NW Washington, DC 20001", + "website": "https://example.com/awesomecomp/awesomepc1/details" + }, + "motherboard": { + "product-name": "ISA Corp Magestic Model M-Ultra Motherboard", + "type": "atx", + "cpu": { + "product-name": "ISA Corp Superchip Model 1 4-core Processor", + "architecture": "x86-64", + "speed": "4.7 gigahertz" + }, + "ata-socket": { + "product-name": "ISA Corp SuperSATA Model 2 Storage Socket", + "type": "sata" + }, + "memory-modules": [ + { + "product-name": "Massive Memory Corp Model 3 DDR4-3200 8GB (Module 1)", + "byte-size": 8589934592 + }, + { + "product-name": "Massive Memory Corp Model 3 DDR4-3200 8GB (Module 2)", + "byte-size": 8589934592 + } + ] + } + } +} +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight xml >}} + + + + AwesomeComp Incorportated +
1000 K Street NW Washington, DC 20001
+ https://example.com/awesomecomp/awesomepc1/details + + + ISA Corp Magestic Model M-Ultra Motherboard + atx + + ISA Corp Superchip Model 1 4-core Processor + x86-64 + 4.7 gigahertz + + + ISA Corp SuperSATA Model 2 Storage Socket + sata + + + Massive Memory Corp Model 3 DDR4-3200 8GB (Module 1) + 8589934592 + + + Massive Memory Corp Model 3 DDR4-3200 8GB (Module 2) + 8589934592 + + + +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight yaml >}} +--- +computer: + id: awesomepc1 + vendor: + id: vendor1 + name: AwesomeComp Incorportated + address: 1000 K Street NW Washington, DC 20001 + website: https://example.com/awesomecomp/awesomepc1/details + motherboard: + product-name: ISA Corp Magestic Model M-Ultra Motherboard + type: atx + cpu: + product-name: ISA Corp Superchip Model 1 4.7 GHz 4-core Processor + architecture: x86-64 + speed: 4.7 gigahertz + ata-socket: + product-name: ISA Corp SuperATA Model 2 Socket for SATA Drive + type: sata + memory-modules: + - product-name: Massive Memory Corp Model 3 8GB DDR4-3200 (Module 1) + size: 8589934592 + - product-name: Massive Memory Corp Model 3 8GB DDR4-3200 (Module 2) + size: 8589934592 +{{< /highlight >}} +{{% /tab %}} +{{< /tabs >}} + +With the expressive power of assemblies, flags, and fields, we can specify complex managed objects and control the structure of the intended information model in the resulting data formats. + +Our Metaschema-enabled tools can parse and generate the different data formats. We specify flags on the `computer` assembly, but all else we define in the `model` of the `assembly`. And within that model, we can define the motherboard `assembly` inline with its own `flag` and `model`. XML has different syntax and semantics from JSON and YAML that would lead to structural limitations we would need to work around ourselves by manually designing separate data formats without Metaschema. With Metaschema, we can use `group-as` declarations in our definition, and Metaschema-enabled tools will generate and parse instances for us as instances of the same, despite these limitations, in different data formats automatically. + +We define the data types for different Metaschema fields and flags. Our Metaschema-enabled tools can leverage pre-compiled schemas or generate their own to enforce `field` and `flag` values that are valid for their type. For example, our Metaschema-enabled tools should accept a valid URI for the `website` field of the vendor `assembly`, but not any arbitrary string. For `byte-size`, they should only accept positive integer values greater than 0, not a decimal point number or string. Metaschema facilitates consistent enforcement of data typing so we developers do not have to. + +We also define the minimum and maximum number of elements for the different assemblies, flags, and field with `min-occurs` and `max-occurs` declarations. In our example, we have an opptional `expansion-card` field in the motherboard `assembly`. Our Metaschema-enabled tools will parse or generate instances as valid with optional fields missing. On the other hand, a motherboard `assembly` missing the CPU `field` should throw errors, as should parsing or generating instances with one that one CPU `field` in the JSON, XML, or YAML format. + +## Refactoring Metaschema Definitions and Deduplicating Code + +We now have a robust information model for a computer we can express in JSON, XML, and YAML data models. But what if we want to enhance the information model? Can we add more information but also refactor to be more expressive while reducing redundancy? With Metaschema, yes we can. + +Our stakeholders determine supply chain information is very important. We need to know vendor information for all the different parts of the computer, specifically a company name and where the company is headquartered. This information should be maintained for not just the computer, but all parts and sub-parts. How can we add this to the Metaschema definition? + +To get started, we can copy-paste vendor `assembly` into all relevent assemblies, not just the top-level computer assembly. + +```xml + + + Computer Model + 0.0.4 + computer + http://example.com/ns/computer + http://example.com/ns/computer + + Computer Assembly + A container object for a computer, its parts, and its sub-parts. + computer + + Computer Identifier + An identifier for classifying a unique make and model of computer. + + + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Motherboard Assembly + A container object for a motherboard in a computer and its sub-parts. + + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Product Name + The product name from the vendor of the computer part. + + + Motherboard Type + The type motherboard layout, at, atx, mini-itx or an alternative. + + + Motherboard Central Processing Unit (CPU) + The model number of the CPU on the motherboard of a computer. + + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Product Name + The product name from the vendor of the computer part. + + + CPU Architecture + The Instruction Set Architecture (ISA) of the processor, x86, x86-64,, arm, or an alternative. + + + CPU Speed + The clock speed of the CPU in megahertz or gigahertz. + + + + + Motherboard Advanced Technology Attachment (ATA) Socket + The model number of ATA socket on the motherboard of a computer. There will only be one socket on any motherboard. + + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Product Name + The product name from the vendor of the computer part. + + + ATA Socket Type + The type of ATA socket on the motherboard , pata (parallel ATA), sata (Serial ATA), or an alternative. + + + + + Motherboard Random Access Memory (RAM) Module(s) + Random access memory hardware installed on the motherboard of a computer. + + + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Product Name + The product name from the vendor of the computer part. + + + Memory Module Size + Size of the memory module in binary, not SI base-10 units, meaning a kilobyte is 1024 bytes, not 1000 bytes. + + + + + Motherboard Expansion Card + The model number of an expansion card connected to the motherboard of a computer. + + + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Product Name + The product name from the vendor of the computer part. + + + Expansion Card Type + The type of expansion card on a motherboard of a computer, such as pci (PCI, e.g. Peripheral Component Interconnect), pcie (PCI Express), or an alternative. + + + + + + + + +``` + +An instance for the model above is below in JSON, XML, and YAML data formats. + +{{< tabs JSON XML YAML >}} +{{% tab %}} +{{< highlight json >}} +{ + "computer": { + "id": "awesomepc1", + "vendor": { + "id": "vendor1", + "name": "AwesomeComp Incorportated", + "address": "1000 K Street NW Washington, DC 20001", + "website": "https://example.com/awesomecomp/" + }, + "motherboard": { + "vendor": { + "id": "vendor2", + "name": "ISA Corp", + "address": "2000 K Street NW Washington, DC 20002", + "website": "https://example.com/isacorp/" + }, + "product-name": "Magestic Model M-Ultra Motherboard", + "type": "atx", + "cpu": { + "vendor": { + "id": "vendor2", + "name": "ISA Corp", + "address": "2000 K Street NW Washington, DC 20002", + "website": "https://example.com/isacorp/" + }, + "product-name": "Superchip Model 1 4-core Processor", + "architecture": "x86-64", + "speed": "4.7 gigahertz" + }, + "ata-socket": { + "vendor": { + "id": "vendor2", + "name": "ISA Corp", + "address": "2000 K Street NW Washington, DC 20002", + "website": "https://example.com/isacorp/" + }, + "product-name": "SuperSATA Model 2 Storage Socket", + "type": "sata" + }, + "memory-modules": [ + { + "vendor": { + "id": "vendor3", + "name": "Massive Memory Corp", + "address": "3000 K Street NW Washington, DC 20003", + "website": "https://example.com/massive-memory-corp/" + }, + "product-name": "Model 3 DDR4-3200 8GB (Module 1)", + "byte-size": 8589934592 + }, + { + "vendor": { + "id": "vendor3", + "name": "Massive Memory Corp", + "address": "3000 K Street NW Washington, DC 20003", + "website": "https://example.com/massive-memory-corp/" + }, + "product-name": "Model 3 DDR4-3200 8GB (Module 2)", + "byte-size": 8589934592 + } + ] + } + } +} +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight xml >}} + + + + AwesomeComp Incorportated +
1000 K Street NW Washington, DC 20001
+ https://example.com/awesomecomp/ + + + + ISA Corp +
2000 K Street NW Washington, DC 20002
+ https://example.com/isacorp/ + + Magestic Model M-Ultra Motherboard + atx + + + ISA Corp +
2000 K Street NW Washington, DC 20002
+ https://example.com/isacorp/> + + Superchip Model 1 4-core Processor + x86-64 + 4.7 gigahertz + + + + ISA Corp +
2000 K Street NW Washington, DC 20002
+ https://example.com/isacorp/ + + SuperSATA Model 2 Storage Socket + sata + + + + Massive Memory Corp +
3000 K Street NW Washington, DC 20003
+ https://example.com/massive-memory-corp/ + + Model 3 DDR4-3200 8GB (Module 1) + 8589934592 + + + + Massive Memory Corp +
3000 K Street NW Washington, DC 20003
+ https://example.com/massive-memory-corp/ + + Model 3 DDR4-3200 8GB (Module 2) + 8589934592 + + + +{{< /highlight >}} +{{% /tab %}} +{{% tab %}} +{{< highlight yaml >}} +--- +computer: + id: awesomepc1 + vendor: + id: vendor1 + name: AwesomeComp Incorportated + address: 1000 K Street NW Washington, DC 20001 + website: https://example.com/awesomecomp/ + motherboard: + vendor: + id: vendor2 + name: ISA Corp + address: 2000 K Street NW Washington, DC 20002 + website: https://example.com/isacorp/ + product-name: Magestic Model M-Ultra Motherboard + type: atx + cpu: + vendor: + id: vendor2 + name: ISA Corp + address: 2000 K Street NW Washington, DC 20002 + website: https://example.com/isacorp/ + architecture: x86-64 + product-name: Superchip Model 1 4-core Processor + speed: 4.7 gigahertz + ata-socket: + vendor: + id: vendor2 + name: ISA Corp + address: 2000 K Street NW Washington, DC 20002 + website: https://example.com/isacorp/ + product-name: SuperSATA Model 2 Storage Socket + type: sata + memory-modules: + - vendor: + id: vendor3 + name: Massive Memory Corp + address: 3000 K Street NW Washington, DC 20003 + website: https://example.com/massive-memory-corp/ + product-name: Model 3 DDR4-3200 8GB (Module 1) + byte-size: 8589934592 + - byte-size: 8589934592 + product-name: Model 3 DDR4-3200 8GB (Module 2) + vendor: + address: 3000 K Street NW Washington, DC 20003 + id: vendor3 + name: Massive Memory Corp + website: https://example.com/massive-memory-corp/ +{{< /highlight >}} +{{% /tab %}} +{{< /tabs >}} + + +We have updated our model to meet stakeholder needs, but the model itself is significantly more verbse. Fortunately, we can use Metaschema syntax to define an `assembly`, `field`, or `flag` once and reuse the definition elsewhere by references with `ref` keyword. We can refactor our definition and do this with the vendor `assembly` and product name `field` in the definition below. + +```xml + + + Computer Model + 0.0.5 + computer + http://example.com/ns/computer + http://example.com/ns/computer + + Vendor Information + Information about a vendor of a computer part. + + Vendor Identifier + An identifier for classifying a unique computer parts vendor. + + + + Vendor Name + The registered company name of the vendor. + + + Vendor Address + The physical address of an office location for the vendor. + + + Vendor Website + A public website made by the vendor documenting their parts as used in the computer. + + + + + Product Name + The product name from the vendor of the computer part. + + + Computer Assembly + A container object for a computer, its parts, and its sub-parts. + computer + + Computer Identifier + An identifier for classifying a unique make and model of computer. + + + + Motherboard Assembly + A container object for a motherboard in a computer and its sub-parts. + + + + Motherboard Type + The type motherboard layout, at, atx, mini-itx or an alternative. + + + Motherboard Central Processing Unit (CPU) + The model number of the CPU on the motherboard of a computer. + + + + + CPU Architecture + The Instruction Set Architecture (ISA) of the processor, x86, x86-64, arm, or an alternative. + + + CPU Speed + The clock speed of the CPU in megahertz or gigahertz. + + + + + Motherboard Advanced Technology Attachment (ATA) Socket + The model number of ATA socket on the motherboard of a computer. There will only be one socket on any motherboard. + + + + + ATA Socket Type + The type of ATA socket on the motherboard , pata (parallel ATA), sata (Serial ATA), or an alternative. + + + + + Motherboard Random Access Memory (RAM) Module(s) + Random access memory hardware installed on the motherboard of a computer. + + + + + + Memory Module Size + Size of the memory module in binary, not SI base-10 units, meaning a kilobyte is 1024 bytes, not 1000 bytes. + + + + + Motherboard Expansion Card + The model number of an expansion card connected to the motherboard of a computer. + + + + + Product Name + The product name from the vendor of the computer part. + + + Expansion Card Type + The type of expansion card on a motherboard of a computer, such as pci (PCI, e.g. Peripheral Component Interconnect), pcie (PCI Express), or an alternative. + + + + + + + + +``` + +We lifted the `assembly` definition for vendor and the definition of the product name `field` to outside the computer `assembly`. Because we have a `root-name` previously defined for the computer `assembly`, Metaschema enabled-tools will work just like before, generating and parsing the same instances with the computer `assembly` as the root, even with multiple top-level elements defined. At the same time, we reduced repeat copy-pasted code, and we can continue to add other requirements from our stakeholders and reuse their definitions across different elements of the model and maintain the original definition once. + +## Conclusion + +In this tutorial, we examined an example of a real-world object in a domain and how we would model it with a community of stakeholders. We created and incrementally improved a Metaschema definition, using it to our advantage for refactoring and modification. In doing so, we learned key Metaschema concepts and their benefits in application. Learning and applying these concepts will prepare us to explore more advanced topics in the following tutorials. diff --git a/website/content/tutorials/_index.md b/website/content/tutorials/_index.md new file mode 100644 index 000000000..ae405c5dd --- /dev/null +++ b/website/content/tutorials/_index.md @@ -0,0 +1,11 @@ +--- +title: "Metaschema Tutorials" +Description: "Collection of Metaschema tutorials" +heading: Getting Started with Metaschema +menu: + primary: + name: Tutorials + weight: 10 +--- + +The following tutorials provide walk-throughs for developers to understand Metaschema, its use cases, and how to use or develop news to exercise them. diff --git a/website/content/use/_index.md b/website/content/use/_index.md index 75bc2bdaf..22ade7ada 100644 --- a/website/content/use/_index.md +++ b/website/content/use/_index.md @@ -10,4 +10,4 @@ menu: Currently, the Metaschema syntax uses an [XML-based format](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema.xsd). Alternate formats (e.g., JSON, YAML) are currently being considered. -An [ISO Schematron](http://schematron.com/) ruleset is also [provided]https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema-composition-check.sch) to enforce some of the rules described below. +An [ISO Schematron](http://schematron.com/) ruleset is also [provided](https://github.com/usnistgov/metaschema/blob/master/toolchains/xslt-M4/validate/metaschema-composition-check.sch) to enforce some of the rules described below. diff --git a/website/static/img/computer.svg b/website/static/img/computer.svg new file mode 100644 index 000000000..6e6900b4b --- /dev/null +++ b/website/static/img/computer.svg @@ -0,0 +1,874 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/website/static/img/computer_numbered.svg b/website/static/img/computer_numbered.svg new file mode 100644 index 000000000..f21dd2b07 --- /dev/null +++ b/website/static/img/computer_numbered.svg @@ -0,0 +1,927 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/website/themes/uswds b/website/themes/uswds index 631e1143c..ac7915f3f 160000 --- a/website/themes/uswds +++ b/website/themes/uswds @@ -1 +1 @@ -Subproject commit 631e1143c32fbcfb8a6d7d5ed7d9e093f51a1c2b +Subproject commit ac7915f3fa4d14fde6115b4a88634f46955a8c20 From 1636adad599b8e8910392f6a4c6c300ecec7e927 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Wed, 11 Jan 2023 11:46:11 -0500 Subject: [PATCH 2/2] Apply suggestions from @wendellpiez feedback. --- .../tutorials/1-getting-started/_index.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/website/content/tutorials/1-getting-started/_index.md b/website/content/tutorials/1-getting-started/_index.md index e3f14b7f1..13ba3fb06 100644 --- a/website/content/tutorials/1-getting-started/_index.md +++ b/website/content/tutorials/1-getting-started/_index.md @@ -8,7 +8,7 @@ toc: ## Understanding the Domain and Designing the Model -Metaschema is a framework for consistently organizing information into machine-readable data formats. For example, if we want to build tools to exchange information about computers, how do we represent a computer in a data format? How do we design it to be consistent and reusable across different software? How do we benefit from the right amout of structured information about computers in that format? +Metaschema is a framework for consistently organizing information into machine-readable data formats. For example, if we want to build tools to exchange information about computers, how do we represent a computer in a data format? How do we design it to be consistent and reusable across different software? How do we benefit from the right amount of structured information about computers in that format? To start organizing this information consistently, we need to consider our mental model of what a computer is. We have to think of the different parts of a computer, sub-parts, and how to compose those parts into a whole. Let's consider a computer such as one visualized below. @@ -20,7 +20,7 @@ In Metaschema terms, this design process is making an [information model](/speci ## Metaschema Concepts -Metaschema helps developers to define models once, in a Metaschema definition. The definition specifies the model of information for the managed object in supported machine-readable data formats. A document in such a format is an instance of that definition. A schema can be used to check the instance is well-formed and valid against the definition's specification. +Metaschema helps developers to define models once, in a Metaschema definition. The definition specifies the model of information for the managed object in supported machine-readable data formats. A document in such a format is an instance of that definition. A schema can be used to check the instance is well-formed and valid against the definition's specification. Such schemas can be derived deterministically and programmatically from a Metaschema definition (or "metaschema"). {{}} @@ -44,7 +44,7 @@ We start with an empty Metaschema definition, like the one below, saved in a fil ``` -Metschema definitions, like the one above, are in XML. A definition begins and ends with capitalized `METASCHEMA` tags. This definition is an empty file, and it is not a valid, well-formed defintion. It is simply the base we will start with. Within those beginning and ending tags, we want to add useful metadata for both developers and Metaschema-enabled tools to consume this definition, like below. +Metschema definitions, like the one above, are in XML. A definition begins and ends with capitalized `METASCHEMA` tags. This definition is an empty file, and it is not a valid, well-formed defintion. It is simply the base we will start with. Within those beginning and ending tags, we want to add useful metadata for both developers and Metaschema-enabled tools to consume this definition, as below. ```xml @@ -58,9 +58,9 @@ Metschema definitions, like the one above, are in XML. A definition begins and e ``` -The metadata above provides useful information to to us Metaschema developers and ours tools that parse Metaschema definitions. The `schema-name` is the long-form, descriptive name of the computer model. The `schema-version` is to give the model itself a version number, for either developers or their tools to use. The `short-name` is the shortened form of the `schema-name`. Normally, Metaschema-enabled tools will parse or generate data with this name `computer`, not `Computer Model`. The `namespace` is a URI used to identify the model and its parts as belonging to a single scope for XML data and schemas. Similarly, the `json-base-uri` serves a similar purpose for JSON data and schemas. +The metadata above provides useful information to us Metaschema developers and our tools that parse Metaschema definitions. The `schema-name` is the long-form, descriptive name of the computer model. The `schema-version` is to give the model itself a version number, for either developers or their tools to use. The `short-name` is the shortened form of the `schema-name`. Normally, Metaschema-enabled tools will parse or generate data with this name `computer`, not `Computer Model`. The `namespace` is a URI used to identify the model and its parts as belonging to a single scope for XML data and schemas. Similarly, the `json-base-uri` serves a similar purpose for JSON data and schemas. -It is important to note this definition is just a starting point. This definition is the most minimally viable definition possible: it is well-formed and valid against [the XML Schema for the Metaschema syntax itself](), but our Metaschema-enabled tools should consider this an empty definition. We have not yet declared a `root-name` and there is no data model yet, so let's start one. We will begin by desinging a computer object to have just an identifier. +It is important to note this definition is just a starting point. This definition is the most minimally viable definition possible: it is well-formed and valid against [the XML Schema for the Metaschema syntax itself](), but our Metaschema-enabled tools should consider this an empty definition. We have not yet declared a `root-name` and there is no data model yet, so let's start one. We will begin by designing a computer object to have just an identifier. We will now add to the [`assembly`](/specification/concepts/terminology/#assembly) for a computer itself and give it an identifier `flag`. @@ -84,7 +84,7 @@ We will now add to the [`assembly`](/specification/concepts/terminology/#assembl ``` -With the definition of the first `assembly` our Metaschema definition takes shape. Firstly, we now add the `root-name` element to identify for Metaschema-enabled tools this `assembly`, whether there are one or more top-level ones defined, is the root element of our data models. This will come in handy later. In the `assembly` declaration, we have defined a `computer` that must have an `id`, and it must the value of it must be a `string`. With Metaschema-enabled tooling, we can have information about a computer like below in their respective JSON, XML, and YAML data formats. +With the definition of the first `assembly` our Metaschema definition takes shape. Firstly, we now add the `root-name` element to identify for Metaschema-enabled tools this `assembly`, whether there are one or more top-level ones defined, is the root element of our data models. This will come in handy later. In the `assembly` declaration, we have defined a `computer` that must have an `id`, the value of which must be `string`. With Metaschema-enabled tooling, we can have information about a computer like below in their respective JSON, XML, and YAML data formats. An instance for the model above is below in JSON, XML, and YAML data formats. @@ -401,11 +401,11 @@ computer: With the expressive power of assemblies, flags, and fields, we can specify complex managed objects and control the structure of the intended information model in the resulting data formats. -Our Metaschema-enabled tools can parse and generate the different data formats. We specify flags on the `computer` assembly, but all else we define in the `model` of the `assembly`. And within that model, we can define the motherboard `assembly` inline with its own `flag` and `model`. XML has different syntax and semantics from JSON and YAML that would lead to structural limitations we would need to work around ourselves by manually designing separate data formats without Metaschema. With Metaschema, we can use `group-as` declarations in our definition, and Metaschema-enabled tools will generate and parse instances for us as instances of the same, despite these limitations, in different data formats automatically. +Our Metaschema-enabled tools can parse and generate the different data formats. We specify flags on the `computer` assembly, but all else we define in the `model` of the `assembly`. And within that model, we can define the motherboard `assembly` inline with its own `flag` and `model`. These abstract definitions, along with information we provide with them such as names of groups, enables a Metaschema-enabled tool to sort out and distinguish the data points as we wish them to appear differently in a different syntax. A JSON schema can describe a JSON format that is idiomatic in JSON, while an XML Schema can do the same in XML with the same Metaschema model. As this example demonstrates, Metaschema allows developers to render the data independent of the notation used to represent it, and convert into any other notation their tools to support. We define the data types for different Metaschema fields and flags. Our Metaschema-enabled tools can leverage pre-compiled schemas or generate their own to enforce `field` and `flag` values that are valid for their type. For example, our Metaschema-enabled tools should accept a valid URI for the `website` field of the vendor `assembly`, but not any arbitrary string. For `byte-size`, they should only accept positive integer values greater than 0, not a decimal point number or string. Metaschema facilitates consistent enforcement of data typing so we developers do not have to. -We also define the minimum and maximum number of elements for the different assemblies, flags, and field with `min-occurs` and `max-occurs` declarations. In our example, we have an opptional `expansion-card` field in the motherboard `assembly`. Our Metaschema-enabled tools will parse or generate instances as valid with optional fields missing. On the other hand, a motherboard `assembly` missing the CPU `field` should throw errors, as should parsing or generating instances with one that one CPU `field` in the JSON, XML, or YAML format. +We also define the minimum and maximum number of elements for the different assemblies, flags, and field with `min-occurs` and `max-occurs` declarations. In our example, we have an optional `expansion-card` field in the motherboard `assembly`. Our Metaschema-enabled tools will parse or generate instances as valid with optional fields missing. On the other hand, a motherboard `assembly` missing the CPU `field` should throw errors, as should parsing or generating instances with one that one CPU `field` in the JSON, XML, or YAML format. ## Refactoring Metaschema Definitions and Deduplicating Code @@ -413,7 +413,7 @@ We now have a robust information model for a computer we can express in JSON, XM Our stakeholders determine supply chain information is very important. We need to know vendor information for all the different parts of the computer, specifically a company name and where the company is headquartered. This information should be maintained for not just the computer, but all parts and sub-parts. How can we add this to the Metaschema definition? -To get started, we can copy-paste vendor `assembly` into all relevent assemblies, not just the top-level computer assembly. +For now, we can copy-paste vendor `assembly` into all relevent assemblies, not just the top-level computer assembly. ```xml @@ -947,7 +947,7 @@ We have updated our model to meet stakeholder needs, but the model itself is sig ``` -We lifted the `assembly` definition for vendor and the definition of the product name `field` to outside the computer `assembly`. Because we have a `root-name` previously defined for the computer `assembly`, Metaschema enabled-tools will work just like before, generating and parsing the same instances with the computer `assembly` as the root, even with multiple top-level elements defined. At the same time, we reduced repeat copy-pasted code, and we can continue to add other requirements from our stakeholders and reuse their definitions across different elements of the model and maintain the original definition once. +We lifted the `assembly` definition for vendor and the definition of the product name `field` to outside the computer `assembly`. Because we have a `root-name` previously defined for the computer `assembly`, Metaschema-enabled tools will work just as before, generating and parsing the same instances with the computer `assembly` as the root, even with multiple top-level elements defined. At the same time, we reduced repeat copy-pasted code, and we can continue to add other requirements from our stakeholders and reuse their definitions across different elements of the model and maintain the original definition once. ## Conclusion