diff --git a/website/content/tutorials/3-constraints-expect/_index.md b/website/content/tutorials/3-constraints-expect/_index.md index b4c2175e..3b422018 100644 --- a/website/content/tutorials/3-constraints-expect/_index.md +++ b/website/content/tutorials/3-constraints-expect/_index.md @@ -824,6 +824,277 @@ We can use the samples above to simulate a scenario where a developer or their t | | ``
`1048576` | `(1048576 mod 1024) = 0` | true | | memory-same-byte-size | Sequence of
(`...... (Module 1)1048555`,
`...... (Module 2)1048576`) | `(sum((8589934592, 8589934592)) mod 8589934592) = 0)` | true | +## Deprecation warnings with `expect` + +With our use of the `expect` constraint for logical value testing, our stakeholders were very pleased we can develop and test small model enhancements incrementally and quickly. However, the adoption of a standard information model and data formats have surfaced some problems and challenges they were unaware of, so they need our help. An important group in their consortium identified a risk around using `byte-size` with binary base-two number for memory or storage capacity. [Binary prefixes](https://en.wikipedia.org/wiki/Binary_prefix) are ambiguous in the updated model. Some vendors use binary base-two sizes or decimal base-ten sizes, but this field in the model makes tooling inconsistent and document instances unclear. A majority in the consortium decided updates to documentation (sourced from our Metaschema modules) are not enough. There must be a way to identify size, its unit prefix (binary or decimal), and optionally a unit so developers and software do not need to compute the full byte size. Our stakeholders are very concerned because the consortium also wants to allow the old approach in our information model and mark this method as deprecated. The intent will be to remove after twelve to twenty four months. + +Fortunately for us, this risk is worrisome to the stakeholders, but very relatable and easy to change for us Metaschema module developers. The `expect` constraints, paired with model changes with `choice` or other strategies, allow us to change the information model and data formats and standardize deprecation messaging across tools. + +Given these new requirements we will add a new assembly, `size`. We will amend the model to allow using `bytes-size` like before or the new `size` assembly. And finally, we will amend the constraints to add a deprecation warning and recommend developers to transition software and existing documents to the new model structure. + +```xml {linenos=table,hl_lines=["152-212","253-255"]} + + + + Computer Model + 0.0.9 + 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. + + + 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. + + + Memory Module Size + Size of memory module in binary or SI base-10 units, optionally with a size unit. This does not require to be in bits or bytes. + + Memory Module Size Unit + The unit size for a memory module can either be bytes (B) or bits (b). + + + byte + bit + + + + + Memory Module Size Unit Prefix Base + The prefix type of module size, binary or decimal. This is useful if you will not specify an optional unit or unit base. + + + + + + + + + Memory Module Size Unit Prefix + The optional prefix the of unit from a given system. + + + + + + + + + + + + + Memory Module Size Unit Prefix System + An identifier for the organization associated with the specific usage of unit prefix. If absent, the International System of Units (SI) is the presumed default. + + + The International Electrotechnical Commission 60027-2 Amendment 2 Units + JEDEC Solid State Technology Association Units + International System of Units + + + + + + + + + All memory modules SHOULD use size because byte-size is now deprecated and byte-size will be removed. + + + + + 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. + + + + + + + All memory modules SHOULD be the same size or byte-size for a computer. + + + + + + +``` + ## Conclusion In this tutorial, we examined advanced usage of constraints to precisely control the structure of values without knowledge of an exhaustive, predetermined list.