One principle is that the goal of serialization is to put Elements into physical format, NOT to create new elements that didn't exist prior to serialization. If you have 6 elements going into serialization, you should have 6 elements coming out, not 7.
The second principle is that logical elements should be independent: the value of one element does not depend on the value of any other element. I believe that those two principles are worth adopting as design requirements. It is ugly to put something into serialization and get something else back out, and it's really ugly to stuff one element's value inside another, not least because you can wind up with infinite recursion with documents inside documents inside documents inside documents. Even two levels of element nesting makes things quite difficult to disentangle. The fundamental principle is that a file containing data is not an element. A Transfer Unit is defined by a data schema, just like the content of any XML file or JSON file or ASN.1 file. If the logical model has a Document element that describes an X.509 certificate, that element has interesting facts about the certificate but does not define its content. It is essential to remember the difference between the bytes in a file and the properties of a File or Document element - the difference between a thing and metadata about that thing. * defaults: I created a separate defaults property to hold the five defaultable properties in order to distinguish them from non-defaultable properties. Gary and I like the idea, but I'm not wedded to it. The transfer unit schema could have "defaultCreatedBy", "defaultCreated", etc properties at the top level, to highlight that they are defaults, unlike name, description, comments, etc. Whatever the mechanism, there must be a way to ensure that "name" doesn't take an inappropriate default value if it isn't populated, while the default for "profiles" is appropriate. * array vs map I used map as a conversation starter, because it fits the "unique" semantics of element ids, and because mapping types are ubiquitous now, XML schema had it in 2005 https://www.w3.org/2005/07/xml-schema-patterns.html#Maps, and it's a built-in part of JSON. JSON-LD even treats ID differently from other properties by giving it a reserved @ID type, and SQL databases have primary keys with the special characteristic that they uniquely identify the record rather than being just another column. Autogenerated ids are often hidden because they are ubiquitous. And finally, you introduced Map to the logical model for Extensions. If it's OK for extensions, it's OK for Elements :-). Seriously though, I'm not wedded to Map. Treating Id as any other property but having some prose saying that it can be used as a primary key / unique identifier is OK, it's just kind of loose given that references from foreign to primary keys is a universal concept. * type property Since JSON does not have types it's good practice to ensure that "type: identity" cannot collide with a property named "identity". At the core profile all type and property names are defined and don't collide, but if "type" goes away we'll need to ensure that properties defined in any profile cannot collide with types defined in any profile. Again JSON-LD treats @type as a reserved property: https://w3c.github.io/json-ld-syntax/#typed-values. * document root A transfer unit file is not an Element and not a logical type or a class. The bytes in SPDX documents are not defined by the logical model, they just have to be able to be de-serialized into element instances. Data schemas (for JSON, XML, ASN.1, ...) explicitly do not define classes, they define only data types. Regards, Dave On Mon, Jul 18, 2022 at 7:08 PM William Bartholomew (CELA) via lists.spdx.org <[email protected]> wrote: > There are some “proposed” examples at the bottom of the model diagram > (note that I intended these to be representative until we define the exact > serialization for each data format): > > https://github.com/spdx/spdx-3-model/blob/main/model.png > > > > Some of the key differences (with no implied support for either choice, I > have included my reasoning for reference only): > > - Defaults being represented as the original properties on a > collection element *vs* being in their own “defaults” property. > - I was thinking about this as a traditional inheritance/overrides > structure. If a property doesn’t have a value you can walk the tree up > looking for the same property. > - Array of elements *vs* map of elements. > - In the past I have found schema languages don’t have good support > for one of the properties of an object being outside of the object > (i.e. a > key on the collection outside). Having a completely contained object > makes > canonicalization etc. easier at the risk of the array having multiple > instances of the same element (which can be solved in other ways). > - Type being a string property *vs* an object property containing the > type. > - I mainly followed the JSON-LD style and it has one less level of > nesting. > - Document root being an element *vs* a custom class. > - Tried to minimize custom classes by having everything as either > an element or a value type. > > > > > > Regards, > > > > William Bartholomew (he/him) – Let’s chat > <https://outlook.office.com/bookwithme/user/[email protected]/meetingtype/SVRwCe7HMUGxuT6WGxi68g2?anonymous&ep=mlink> > > Principal Security Strategist > > Global Cybersecurity Policy – Microsoft > > > > *My working day may not be your working day. Please don’t feel obliged to > reply to this e-mail outside of your normal working hours.* > > > > *From:* [email protected] <[email protected]> *On Behalf Of > *David Kemp via lists.spdx.org > *Sent:* Monday, July 18, 2022 1:56 PM > *To:* SPDX-list <[email protected]> > *Subject:* [EXTERNAL] [spdx-tech] V3 serialization > > > > Last week I took an action item to describe what serialized data for the > v3 logical model could look like, in order to clarify discussion of the > types shown in the model. > > The thing to remember about v3 is that it is knowledge graph centric, not > document centric. Element instances from the knowledge graph can be > serialized into data instances, but the data definition is controlled by > the logical model, not vice versa. Data examples in various formats can > illustrate the logical model for readers of the v3 spec, but they do not > define it as they do in SPDX v2. > > A collection of independent element values is shown in > "logical-elements". JSON data is use to visualize the element values, but > it is important to remember that the logical value itself is the ability to > answer questions: > * what is the id of this element? > * what is the type of this element? > * who created this element? > etc. The element is a class with getters that allow each property of an > instance to be retrieved, and those property values are independent of > serialization format. > > That collection of elements can be serialized into a transfer unit file as > shown in "transfer units" > > A Document element describes the contents of a transfer unit, but does not > need to be present in the transfer unit. The example transfer unit > containing six elements (an SBOM, a Package, two Files, a Relationship, and > an Actor that created them) is: > > { > "namespace": "urn:acme.dev > <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Facme.dev%2F&data=05%7C01%7Cwillbar%40microsoft.com%7Cc4d9ad6e7dff4688466708da68fffc92%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637937746360883486%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=T5QvsuS%2FVFyaRYWS5tndAZ%2FZZuH3DyRaJbioFtrcsp8%3D&reserved=0> > :", > "defaults": { > "createdBy": ["identities:fred"], > "created": "2022-04-05T22:00:00Z", > "specVersion": "3.0", > "profiles": ["Core", "Software"], > "dataLicense": "CC0-1.0" > }, > "elementValues": { > "artifacts:gnu-coreutils/v9.1/src/du.c": { > "type": { > "file": { > "filePurpose": ["APPLICATION", "SOURCE"] > } > } > }, > "artifacts:gnu-coreutils/v9.1/src/echo.c": { > "type": { > "file": { > "filePurpose": ["APPLICATION", "SOURCE"] > } > } > }, > "artifacts:gnu-coreutils/v9.1": { > "type": { > "package": { > "packagePurpose": ["APPLICATION", "SOURCE"], > "downloadLocation": " > http://mirror.rit.edu/gnu/coreutils/coreutils-9.1.tar.gz > <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fmirror.rit.edu%2Fgnu%2Fcoreutils%2Fcoreutils-9.1.tar.gz&data=05%7C01%7Cwillbar%40microsoft.com%7Cc4d9ad6e7dff4688466708da68fffc92%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637937746360883486%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=eInMx9WfEgJLdnlb34RodbwRWexAALR0h%2F3udX89tzY%3D&reserved=0> > ", > "homePage": "https://www.gnu.org/software/coreutils/ > <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.gnu.org%2Fsoftware%2Fcoreutils%2F&data=05%7C01%7Cwillbar%40microsoft.com%7Cc4d9ad6e7dff4688466708da68fffc92%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637937746360883486%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=uSQrc0%2BDv6aitasWrisDyOJH1FmbcLCc2PawF%2Ffl4Wc%3D&reserved=0> > " > } > }, > "name": "GNU Coreutils" > }, > "relationships:gnu-coreutils/v9.1": { > "type": { > "relationship": { > "relationshipType": "CONTAINS", > "from": "urn:acme.dev:artifacts:gnu-coreutils/v9.1", > "to": [ > "artifacts:gnu-coreutils/v9.1/src/du.c", > "artifacts:gnu-coreutils/v9.1/src/echo.c" > ] > } > } > }, > "identities:fred": { > "type": { > "actor": {} > }, > "identifiedBy": [{"email": "[email protected]"}] > }, > "sboms:gnu-coreutils/v9.1": { > "type": { > "sbom": { > "elements": [ > "artifacts:gnu-coreutils/v9.1/src/du.c", > "artifacts:gnu-coreutils/v9.1/src/echo.c", > "artifacts:gnu-coreutils/v9.1", > "relationships:gnu-coreutils/v9.1", > "identities:fred" > ] > } > } > } > } > } > > The element examples, transfer unit examples, and the SPDX v3 schema > derived from the logical model are available in > https://github.com/davaya/spdx-3-elements > <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fdavaya%2Fspdx-3-elements&data=05%7C01%7Cwillbar%40microsoft.com%7Cc4d9ad6e7dff4688466708da68fffc92%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637937746360883486%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=jot0np%2BhQEDqPjitLgAzwKut9GXZruQaxuzhYp6SvvE%3D&reserved=0> > . > > The intent is for these to assist in refining the logical model and its > serializations together. > > Regards, > Dave > > > > -=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#4658): https://lists.spdx.org/g/Spdx-tech/message/4658 Mute This Topic: https://lists.spdx.org/mt/92468742/21656 Group Owner: [email protected] Unsubscribe: https://lists.spdx.org/g/Spdx-tech/unsub [[email protected]] -=-=-=-=-=-=-=-=-=-=-=-
