Document ID constraints for non element nodes
Opened this issue · 6 comments
During the discussion on resolving the Individual Creation Infos, the issue was raised that we are not properly documenting the ID constraints for non Element classes.
We should document this this either in the model, serialization spec, or the using repo - actual location TBD.
From previous minutes and discussions:
CreationInfo
Summary
Provides information about the creation of the Element.
Description
The CreationInfo provides information about who created the Element, and when and how it was created.
The dateTime created is often the date of last change (e.g., a git commit date), not the date when the SPDX data was created, as doing so supports reproducible builds.
Metadata
name: CreationInfo
Instantiability: Concrete
Properties
< id > a globally unique URI identifier must be present for all instances of this class in deserialized form. In serialized form an identifier may be present for instances of this class as a globally unique URI identifier, as a locally unique string identifier, or not present at all if the instance of this class is embedded (e.g., blank node) within the instance of an Element class it is characterizing. Specific identifier requirements including presence, form, and property name for any given serialization form are defined in the relevant serialization binding rules.
model constraints
type: xsd:anyURI
minCount: 1
maxCount: 1
serialization constraints
type: xsd:string
maxCount: 1
specVersion
type: SemVer
minCount: 1
maxCount: 1
comment
type: xsd:string
minCount: 0
maxCount: 1
created
type: DateTime
minCount: 1
maxCount: 1
createdBy
type: Agent
minCount: 1
createdUsing
type: Tool
minCount: 0
Note that the git history does not show the above changes, they are from prior minutes.
In my experience, a relatively small percentage of SPDX implementers use or follow RDF standards, so I think it is important that we write the documentation in a way that makes sense to all audiences.
At the same time, we do need to communicate the difference between element IDs and non element class ids for graph implementations.
Based on this - I would propose we write up documentation in the context of describing what an SPDX Element is and how it differs from other classes in a general sense. We could then write up more specific implementation advice if coming from the RDF perspective.
Concepts that we could communicate:
- Elements are the "atomic" unit of data to be transferred or exchanged
- Elements must have a globally unique ID in the form of a URI
- Elements can be externally referenced
- Any properties of elements which are not themselves elements need to be exchanged along with the element
- In RDF, non-element properties can be blank nodes
- Non-element properties are not intended to be shared externally - the SPDX standard does not provide a mechanism for validating external non-element properties like it does for element properties.
From discussion on the outreach call - idea is to start the documentation with a statement that there are 2 communities or two approaches we are trying solve:
- Pure RDF graph implementations - highly granular
- SPDX 2.X compatible document exchange implementations