From a636def3521c91ece28f5e8caf54b4fc07249e12 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 16 Jan 2024 14:38:54 -0500 Subject: [PATCH] Recommended values section and conclusion for #292 Add introduction and section about how to defined mandatory, recommended values for `allowed-values allow-other="yes"` for the first segment of the tutorial. Added a conclusion for wrap-up given the current draft contents. --- .../content/tutorials/2-constraints/_index.md | 436 ++++++++++++++++++ 1 file changed, 436 insertions(+) diff --git a/website/content/tutorials/2-constraints/_index.md b/website/content/tutorials/2-constraints/_index.md index c3564e1a..aa5d039a 100644 --- a/website/content/tutorials/2-constraints/_index.md +++ b/website/content/tutorials/2-constraints/_index.md @@ -630,4 +630,440 @@ computer: {{% /tab %}} {{< /tabs >}} +### Recommended values with `allow-other="yes"` + +The updated model with approved values for CPU architecture was a success with stakeholders. It allowed those using Metaschema-enabled tools to exchange more consistent, accurate data. Now the computer model stakeholders have a new requirement. For the ATA socket type for the motherboard of a computer, stakeholders want to have a set of approved values. Unlike the CPU architecture type, the stakeholders want to maintain flexibility for emerging socket technologies without implementations or names at present. At a minimum, they want the preferred values in the table below to be recommended, but allow alternatives as they emerge. + +| ATA Socket Type | Description | +|-------------------|------------------------------------------------------------------------------------| +| pata | Parallel ATA buses also known as AT-Attachment and IDE | +| sata | Serial ATA buses supporting Advanced Host Controller Interface or legacy IDE modes | +| esata | External Serial ATA buses for pluggable external devices using SATA | +| esatap | External Serial ATA buses supporting SATA traffic and device power | + +To implement such a requirement, we must use an [`` constraint](/specification/syntax/constraints#enumerated-values) to make a list of optional, recommended 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="yes"` declaration means a valid, conforming document instance can use a recommended value from the list, or any other as new types emerge. 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=["143-154"]} + + + 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 with approved (but optional) values recommended by model stakeholders. + + + Parallel ATA buses also known as AT-Attachment and IDE + Serial ATA buses supporting Advanced Host Controller Interface or legacy IDE modes + External Serial ATA buses for pluggable external devices using SATA + External Serial ATA buses supporting SATA traffic and device power + + + + + + + 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. + + + + + + + + +``` + +The previous versions of conforming example document instances are still valid. Using a new value for ATA socket's type will not throw a validation error. Moreover, new example document instances conforming to the module in the the updated Metaschema module for a ATA socket using Serial Attached SCSI with value `sas`. Below are these example document instances. + +{{< 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": "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": "AwesomeSAS Model 1 Storage Socket", + "type": "sas" + }, + "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 + arm64 + 4.7 gigahertz + + + + ISA Corp +
2000 K Street NW Washington, DC 20002
+ https://example.com/isacorp/ + + AwesomeSAS Model 1 Storage Socket + sas + + + + 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: 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: AwesomeSAS Model 1 Storage Socket + type: sas + 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 + +In this tutorial, we examined an example of a real-world information model in a domain and how we would model it with a community of stakeholders. We incrementally improved a Metaschema module to add more precision to values for field and flag elements with the use of constraints.