From 4f4aa7973849f4edf605de6d3ed4bdb591e51452 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 16 Jan 2024 12:45:13 -0500 Subject: [PATCH] Intro and required values section for #292 Add introduction and section about how to defined mandatory, required values for `allowed-values allow-other="no"` for the first segment of the tutorial. --- .../content/tutorials/2-constraints/_index.md | 623 ++++++++++++++++++ 1 file changed, 623 insertions(+) diff --git a/website/content/tutorials/2-constraints/_index.md b/website/content/tutorials/2-constraints/_index.md index abb583cd..1dce8d65 100644 --- a/website/content/tutorials/2-constraints/_index.md +++ b/website/content/tutorials/2-constraints/_index.md @@ -7,4 +7,627 @@ description: "" ## Our use case, the computer model, and next steps +In [the previous tutorial](/tutorials/1-getting-started/), we incrementally designed, implemented, and refactored a computer model and conforming document instances. We learned how to compose elements (flags and fields) into structures (assemblies). We used the type system for simple constraints on element values (i.e. must be an integer number, a string, a date). We refactored the models to reduce repetition (i.e. each computer part having a `vendor`, not just the computer itself, and the model developer defines it only once). But what do when we need to be more precise with values? + +To more precisely control values, a model developer can use constraints, which we will examine in the tutorial below. + +## Constraints + +Elements in the document instances will often require more precise values than the minimum and maximum requirements of a type (i.e. a value must be `green` or `red` but no other value, even if it is still a string). We can require such precision in our models with [constraints](/specification/syntax/constraints/). There are several constraint types, each with their own unique functionality. Let's review our current model and document instances to first understand how to constrain field and flag values with precise, specific values using an `allowed-values` constraint. + +We will begin where we left off in the previous tutorial, with the model and conforming document instances 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. + + + + + + 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. + + + + + + + + +``` +{{< 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 >}} + +## `allowed-values` + +### Required values with `allow-other="no"` + +We have been successful with the Metaschema module above and the Metaschema-enabled tooling that leverages it. However, we must address a new business requirement from the stakeholders for that model. Specific, approved architecture types must be used to identify the CPU of a given computer. Below is the table with the currently approved values. + +| Architecture Type | Description | +|-------------------|-----------------------------------------------------| +| amd64 | Intel 64-bit systems, also known as x86-64 or em64t | +| armhf | Arm v7 32-bit systems | +| arm64 | Arm v8 64-bit systems | +| x86 | Intel 32-bit x86 systems, for 686 class or newer | + +To implement such a requirement, we cannot rely on type system alone. We must use an [`` constraint](/specification/syntax/constraints#enumerated-values) to make an explicit list of only supported values. For a field like architecture in the model, we can define it inside the field like below where the change is highlighted. The `allow-other="no"` declaration means a valid, conforming document instance can use only of those values in the architecture field of the CPU and no other value. The constraint definition is inside the architecture field so it is the current context for evaluation focus of the [target](/specification/syntax/constraints#target). The declaration `target="."` makes it explicit. + +```xml {linenos=table,hl_lines=["59-70"]} + + + + 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) approved by module stakeholders. + + + Intel 64-bit systems, also known as x86-64 or em64t + Arm v7 32-bit systems + Arm v8 64-bit systems + Intel 32-bit x86 systems, for 686 class or newer + + + + + 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. + + + + + + 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. + + + + + + + + +``` + +After updating the model, the examples above are no longer valid. A Metaschema processor will throw a validation error for the CPU architecture field. We need to edit the CPU architecture field with the required value that reflects the same information, `arm64`. + +{{< tabs JSON XML YAML >}} +{{% tab %}} +{{< highlight json "linenos=table,hl_lines=27" >}} +{ + "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": "arm64", + "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 "linenos=table,hl_lines=23" >}} + + + + 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 + arm64 + 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 "linenos=table,hl_lines=23" >}} +--- +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: arm64 + 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 >}} + ## Conclusion