diff --git a/website/content/tutorials/_index.md b/website/content/tutorials/_index.md index fd157da5a..e31c5b4fc 100644 --- a/website/content/tutorials/_index.md +++ b/website/content/tutorials/_index.md @@ -75,6 +75,7 @@ With a minimal metadata section in place, we will add the first part of the mode 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. @@ -301,7 +302,7 @@ A JSON instance for the computer model is below. "id": "vendor1", "name": "AwesomeComp Incorportated", "address": "1000 K Street NW Washington, DC 20001", - "website": "https://example.com/awesomepc1/details" + "website": "https://example.com/awesomecomp/awesomepc1/details" }, "motherboard": { "product-name": "ISA Corp Magestic Model M-Ultra Motherboard", @@ -323,7 +324,7 @@ A JSON instance for the computer model is below. { "product-name": "Massive Memory Corp Model 3 DDR4-3200 8GB (Module 2)", "byte-size": 8589934592 - }, + } ] } } @@ -338,7 +339,7 @@ An XML instance for the computer model is below. AwesomeComp Incorportated
1000 K Street NW Washington, DC 20001
- https://example.com/awesomepc1/details + https://example.com/awesomecomp/awesomepc1/details ISA Corp Magestic Model M-Ultra Motherboard @@ -374,7 +375,7 @@ computer: id: vendor1 name: AwesomeComp Incorportated address: 1000 K Street NW Washington, DC 20001 - website: https://example.com/awesomepc1/details + website: https://example.com/awesomecomp/awesomepc1/details motherboard: product-name: ISA Corp Magestic Model M-Ultra Motherboard type: atx @@ -386,10 +387,10 @@ computer: 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 + - 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 ``` 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. @@ -402,19 +403,21 @@ We also define the minimum and maximum number of elements for the different asse ## Refactoring Metaschema Definitions and Deduplicating Code -We now have a robust information model for a computer we can express in JSON, XML, and YAML. But what if we want to enhance the information model. Our stakeholders determine supply chain information is very important. They want to know the 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 its parts and sub-parts. How can we add this to the Metaschema definition? +We now have a robust information model for a computer we can express in JSON, XML, and YAML. 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. They want to know the 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 its parts and sub-parts. How can we add this to the Metaschema definition? -We start with a simple but effective solution, we add this vendor information as part of the computer `assembly`. +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.1 + 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. @@ -430,15 +433,15 @@ We start with a simple but effective solution, we add this vendor information as 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. @@ -448,6 +451,28 @@ We start with a simple but effective solution, we add this vendor information as 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. @@ -460,6 +485,28 @@ We start with a simple but effective solution, we add this vendor information as 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. @@ -470,7 +517,7 @@ We start with a simple but effective solution, we add this vendor information as CPU Speed - This is the clock speed of the CPU in megahertz or gigahertz. + The clock speed of the CPU in megahertz or gigahertz. @@ -478,6 +525,28 @@ We start with a simple but effective solution, we add this vendor information as 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. @@ -493,6 +562,28 @@ We start with a simple but effective solution, we add this vendor information as 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. @@ -508,6 +599,28 @@ We start with a simple but effective solution, we add this vendor information as 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. @@ -525,6 +638,307 @@ We start with a simple but effective solution, we add this vendor information as ``` -## Metaschema Definitions and Schemas +A JSON instance for the computer model is below. + +```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 + } + ] + } + } +} +``` + +An XML instance for the computer model is below. + +```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 + 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 + + + +``` + +A YAML instance for the computer model is below. + +```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/ +``` + +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 `ref`. 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, 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`. 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 -A Metaschema definition is a machine-readble format to describe a model of information, like the example definition with the computer model. Metaschema-enabled tools can relate a definiton to an instance, but how do we check for well-formed and valid data? We use Metaschema syntax and semantics so we can consistently not only form data, but also relate instances to schemas. For basic Metaschema-enabled tools, we expect parsing an instance based on a definition to conform to a schema. For advanced Metaschema-enabled tools, we expect the tool to read a definition and generate a schema for supported data format. For JSON and YAML instances, we use JSON Schema. For XML, we use XML Schema. +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/computer_metaschema.xml b/website/content/tutorials/computer_metaschema.xml deleted file mode 100644 index 831a0b429..000000000 --- a/website/content/tutorials/computer_metaschema.xml +++ /dev/null @@ -1,116 +0,0 @@ - - - Computer Model - 0.0.1 - 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 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, arm, or an alternative. - - - CPU Speed - This is 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. - - - - - - - - diff --git a/website/content/tutorials/minimal_metaschema.xml b/website/content/tutorials/minimal_metaschema.xml deleted file mode 100644 index b9606109c..000000000 --- a/website/content/tutorials/minimal_metaschema.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - Computer Model - 0.0.1 - computer - http://example.com/ns/computer - http://example.com/ns/computer - - \ No newline at end of file